1 files changed, 51 insertions, 0 deletions
diff --git a/src/doc/rust-by-example/src/fn.md b/src/doc/rust-by-example/src/fn.md
new file mode 100644
index 000000000..e77552271
--- /dev/null
+++ b/src/doc/rust-by-example/src/fn.md
@@ -0,0 +1,51 @@
+# Functions
+
+Functions are declared using the `fn` keyword. Its arguments are type
+annotated, just like variables, and, if the function returns a value, the
+return type must be specified after an arrow `->`.
+
+The final expression in the function will be used as return value.
+Alternatively, the `return` statement can be used to return a value earlier
+from within the function, even from inside loops or `if` statements.
+
+Let's rewrite FizzBuzz using functions!
+
+```rust,editable
+// Unlike C/C++, there's no restriction on the order of function definitions
+fn main() {
+    // We can use this function here, and define it somewhere later
+    fizzbuzz_to(100);
+}
+
+// Function that returns a boolean value
+fn is_divisible_by(lhs: u32, rhs: u32) -> bool {
+    // Corner case, early return
+    if rhs == 0 {
+        return false;
+    }
+
+    // This is an expression, the `return` keyword is not necessary here
+    lhs % rhs == 0
+}
+
+// Functions that "don't" return a value, actually return the unit type `()`
+fn fizzbuzz(n: u32) -> () {
+    if is_divisible_by(n, 15) {
+        println!("fizzbuzz");
+    } else if is_divisible_by(n, 3) {
+        println!("fizz");
+    } else if is_divisible_by(n, 5) {
+        println!("buzz");
+    } else {
+        println!("{}", n);
+    }
+}
+
+// When a function returns `()`, the return type can be omitted from the
+// signature
+fn fizzbuzz_to(n: u32) {
+    for n in 1..=n {
+        fizzbuzz(n);
+    }
+}
+```