From 8a97d519dcdc53e15127c53e24a52436bfd23b12 Mon Sep 17 00:00:00 2001
From: jonmeow <46229924+jonmeow@users.noreply.github.com>
Date: Wed, 12 Jan 2022 01:13:57 +0000
Subject: [PATCH 01/16] Updating function and variable docs

---
 docs/design/functions.md      | 171 +++++++++++++++++++++++++++-------
 docs/design/type_inference.md |  51 ++++++++++
 docs/design/variables.md      |  11 ++-
 3 files changed, 195 insertions(+), 38 deletions(-)
 create mode 100644 docs/design/type_inference.md

diff --git a/docs/design/functions.md b/docs/design/functions.md
index 12b93b627f362..c03022179cbb9 100644
--- a/docs/design/functions.md
+++ b/docs/design/functions.md
@@ -10,54 +10,153 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 ## Table of contents
 
--   [TODO](#todo)
--   [Basic functions](#basic-functions)
+-   [Overview](#overview)
+-   [Function definitions](#function-definitions)
+    -   [Return clause](#return-clause)
+    -   [`return` statements](#return-statements)
+-   [Function declarations](#function-declarations)
+-   [Function calls](#function-calls)
+-   [Alternatives considered](#alternatives-considered)
+-   [References](#references)
 
 <!-- tocstop -->
 
-## TODO
+## Overview
 
-This is a skeletal design, added to support [the overview](README.md). It should
-not be treated as accepted by the core team; rather, it is a placeholder until
-we have more time to examine this detail. Please feel welcome to rewrite and
-update as appropriate.
+Functions are the core building block for applications. Carbon's basic function
+syntax is:
 
-## Basic functions
+<!-- The \ is for https://github.com/prettier/prettier/issues/9099 -->
 
-Programs written in Carbon, much like those written in other languages, are
-primarily divided up into "functions" (or "procedures", "subroutines", or
-"subprograms"). These are the core unit of behavior for the programming
-language. Let's look at a simple example to understand how these work:
+-   _arg#_: _identifier_ `:` _expression_
+-   _return-clause_: _[_ `->` _< expression |_ `auto` _> ]_
+-   _signature_: `fn` _identifier_ `(` _[ arg1_ `,` _arg2_ `,` _... ]_ `)`
+    _return-clause_
+-   _function-definition_: _signature_ `{` _statements_ `}`
+-   _function-declaration_: _signature_ `;`
+-   _function-call_: _identifier_ `(` _[ expression_ `,` _expression_ `,` _...
+    ]_ `)`
 
+A function with only a signature and no body is a function declaration, or
+forward declaration. When the body is a present, it's a function definition. The
+body introduces nested scopes which may contain local local variable
+declarations.
+
+## Function definitions
+
+A basic function definition may look like:
+
+```carbon
+fn Add(a: i64, b: i64) -> i64 {
+  return a + b;
+}
 ```
-fn Sum(a: Int, b: Int) -> Int;
+
+This declares a function called `Add` which accepts two `i64` parameters, the
+first called `a` and the second called `b`, and returns an `i64` result. It
+returns the result of adding the two arguments.
+
+C++ might declare the same thing:
+
+```cpp
+std::int64_t Add(std::int64_t a, std::int64_t b) {
+  return a + b;
+}
+
+// Or with trailing return type syntax:
+auto Add(std::int64_t a, std::int64_t b) -> std::int64_t {
+  return a + b;
+}
 ```
 
-This declares a function called `Sum` which accepts two `Int` parameters, the
-first called `a` and the second called `b`, and returns an `Int` result. C++
-might declare the same thing:
+### Return clause
+
+The return clause of a function specifies the return type using one of three
+possible syntaxes:
+
+-   `->` followed by an _expression_, such as `i64`, directly states the return
+    type. This expression will be evaluated at compile-time, so must be valid in
+    that context.
+    -   For example, `fn ToString(val: i64) -> String;` has a return type of
+        `String`.
+-   `->` followed by the `auto` keyword indicates that
+    [type inference](type_inference.md) should be used to determine the return
+    type.
+    -   For example, `fn Echo(val: i64) -> auto { return val; }` will have a
+        return type of `i64` through type inference.
+    -   Declarations must have a known return type, so `auto` is not valid.
+    -   The function must have precisely one `return` statement. That `return`
+        statement's expression will then be used for type inference.
+-   Omission indicates that the return type is the empty tuple, `()`.
+    -   For example, `fn Sleep(seconds: i64);` is equivalent to
+        `fn Sleep(seconds: i64) -> ();`.
+    -   This is similar to a `void` return in C++.
+
+### `return` statements
+
+The [`return` statement](control_flow/return.md) is essential to function
+control flow. It ends the flow of the function and returns execution to the
+caller. The `return` statement must be used to end control flow of a function
+when a non-empty [return clause](#return-clause) is used. A `return` statement
+must have an expression argument if and only if there is a non-empty return
+clause.
+
+## Function declarations
 
+Functions may be declared separate from the definition by providing only a
+signature, with no body. This provides an API which may be called. For example:
+
+```carbon
+// Declaration:
+fn Add(a: i64, b: i64) -> i64;
+
+// Definition:
+fn Add(a: i64, b: i64) -> i64 {
+  return a + b;
+}
 ```
-std::int64_t Sum(std::int64_t a, std::int64_t b);
 
-// Or with trailing return type syntax:
-auto Sum(std::int64_t a, std::int64_t b) -> std::int64_t;
+The corresponding definition may be provided later in the same file or, when the
+declaration is in an
+[`api` file of a library](code_and_name_organization/#libraries), in the `impl`
+file of the same library. The signature of a function declaration must match the
+corresponding definition. This includes the [return clause](#return-clause);
+even though an omitted return type has equivalent behavior to `-> ()`, the
+presence or omission must match.
+
+A function declaration can be called, and the function definition may be
+provided later in code; for example, the `api` file of a library will often
+contain a function's declaration while the `impl` file contains the definition.
+
+## Function calls
+
+Function calls use a function's identifier to pass multiple expression arguments
+in place of parameters. For example:
+
+```carbon
+fn Add(a: i64, b: i64) -> i64 {
+  return a + b;
+}
+
+fn Main() {
+  Add(1, 2);
+}
 ```
 
-Let's look at how some specific parts of this work. The function declaration is
-introduced with a keyword `fn` followed by the name of the function `Sum`. This
-declares that name in the surrounding scope and opens up a new scope for this
-function. We declare the first parameter as `Int a`. The `Int` part is an
-expression (here referring to a constant) that computes the type of the
-parameter. The `:` marks the end of the type expression and introduces the
-identifier for the parameter, `a`. The parameter names are introduced into the
-function's scope and can be referenced immediately after they are introduced.
-The return type is indicated with `-> Int`, where again `Int` is just an
-expression computing the desired type. The return type can be completely omitted
-in the case of functions which do not return a value.
-
-Calling functions involves a new form of expression: `Sum(1, 2)` for example.
-The first part, `Sum`, is an expression referring to the name of the function.
-The second part, `(1, 2)` is a parenthesized list of arguments to the function.
-The juxtaposition of one expression with parentheses forms the core of a call
-expression, similar to a postfix operator.
+Here, `Add(1, 2)` is a function call expression. `Add` refers to the function
+definition's identifier. The parenthesized arguments `(1, 2)` are passed to the
+`a` and `b` parameters of `Add`.
+
+## Alternatives considered
+
+-   [Function keyword](/proposals/p0438.md#function-keyword)
+-   [Only allow `auto` return types if parameters are generic](/proposals/p0826.md#only-allow-auto-return-types-if-parameters-are-generic)
+-   [Provide alternate function syntax for concise return type inference](/proposals/p0826.md#provide-alternate-function-syntax-for-concise-return-type-inference)
+-   [Allow separate declaration and definition](/proposals/p0826.md#allow-separate-declaration-and-definition)
+
+## References
+
+-   Proposal
+    [#438: Add statement syntax for function declarations](https://github.com/carbon-language/carbon-lang/pull/438)
+-   Proposal
+    [#826: Function return type inference](https://github.com/carbon-language/carbon-lang/pull/826)
diff --git a/docs/design/type_inference.md b/docs/design/type_inference.md
new file mode 100644
index 0000000000000..984ac73f52af0
--- /dev/null
+++ b/docs/design/type_inference.md
@@ -0,0 +1,51 @@
+# Type inference
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+<!-- toc -->
+
+## Table of contents
+
+-   [Overview](#overview)
+-   [Open questions](#open-questions)
+    -   [Inferring a variable type from literals](#inferring-a-variable-type-from-literals)
+-   [Alternatives considered](#alternatives-considered)
+-   [References](#references)
+
+<!-- tocstop -->
+
+## Overview
+
+[Type inference](https://en.wikipedia.org/wiki/Type_inference) occurs in Carbon
+when the `auto` keyword is used. This may occur in
+[variable declarations](variables.md) or [function declarations](functions.md).
+
+At present, type inference is very simple: given the expression which generates
+the value to be used for type inference, the inferred type is the precise type
+of that expression. For example, the inferred type for `auto` in
+`fn Foo(x: i64) -> auto { return x; }` is `i64`.
+
+Type inference is currently supported for [function return types](functions.md)
+and [declared variable types](variables.md).
+
+## Open questions
+
+### Inferring a variable type from literals
+
+Using the type on the right side for `var y: auto = 1` currently results in a
+constant `IntLiteral(1)` value, whereas most languages would suggest a variable
+integer type, such as `i64`. This is a temporary choice due to the lack of a
+more complete design, and is open to change in the future.
+
+## Alternatives considered
+
+-   [Use `_` instead of `auto`](/proposals/p0851.md#use-_-instead-of-auto)
+
+## References
+
+-   Proposal
+    [#851: auto keyword for vars](https://github.com/carbon-language/carbon-lang/pull/851)
diff --git a/docs/design/variables.md b/docs/design/variables.md
index fc1d725337090..ed8bea30dbdd1 100644
--- a/docs/design/variables.md
+++ b/docs/design/variables.md
@@ -22,7 +22,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 Carbon's local variable syntax is:
 
-> `var` _identifier_`:` _type_ _[_ `=` _value_ _]_`;`
+-   `var` _identifier_`:` _< expression |_ `auto` _> [_ `=` _value_ _]_`;`
 
 Blocks introduce nested scopes and can contain local variable declarations that
 work similarly to function parameters.
@@ -31,7 +31,7 @@ For example:
 
 ```
 fn Foo() {
-  var x: Int = 42;
+  var x: i32 = 42;
 }
 ```
 
@@ -40,6 +40,10 @@ type `Int` and is initialized with the value `42`. These variable declarations
 (and function declarations) have a lot more power than what we're covering just
 yet, but this gives you the basic idea.
 
+If `auto` is used in place of the type, it will use
+[type inference](type_inference.md) to automatically determine the variable
+type.
+
 While there can be global constants, there are no global variables.
 
 ## Notes
@@ -61,6 +65,7 @@ discover that their convenience outweighs any improvements afforded.
 -   [Colon between type and identifier](/proposals/p0339.md#colon-between-type-and-identifier)
 -   [Type elision](/proposals/p0339.md#type-elision)
 -   [Type ordering](/proposals/p0618.md#type-ordering)
+-   [Elide the type instead of using `auto`](/proposals/p0851.md#elide-the-type-instead-of-using-auto)
 
 ## References
 
@@ -68,3 +73,5 @@ discover that their convenience outweighs any improvements afforded.
     [#339: `var` statement](https://github.com/carbon-language/carbon-lang/pull/339)
 -   Proposal
     [#618: `var` ordering](https://github.com/carbon-language/carbon-lang/pull/618)
+-   Proposal
+    [#851: auto keyword for vars](https://github.com/carbon-language/carbon-lang/pull/851)

From ea1d35e7af167a996280c1b3dc3439ab72ee6e78 Mon Sep 17 00:00:00 2001
From: jonmeow <46229924+jonmeow@users.noreply.github.com>
Date: Wed, 12 Jan 2022 01:15:47 +0000
Subject: [PATCH 02/16] Worked around backslash

---
 docs/design/functions.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/design/functions.md b/docs/design/functions.md
index c03022179cbb9..13ea09d904f30 100644
--- a/docs/design/functions.md
+++ b/docs/design/functions.md
@@ -26,8 +26,6 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 Functions are the core building block for applications. Carbon's basic function
 syntax is:
 
-<!-- The \ is for https://github.com/prettier/prettier/issues/9099 -->
-
 -   _arg#_: _identifier_ `:` _expression_
 -   _return-clause_: _[_ `->` _< expression |_ `auto` _> ]_
 -   _signature_: `fn` _identifier_ `(` _[ arg1_ `,` _arg2_ `,` _... ]_ `)`

From 90c0db80c3dbee5f2dcf0f120296883a11d15a39 Mon Sep 17 00:00:00 2001
From: jonmeow <46229924+jonmeow@users.noreply.github.com>
Date: Wed, 12 Jan 2022 01:39:22 +0000
Subject: [PATCH 03/16] Add a couple README updates

---
 docs/design/README.md | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/docs/design/README.md b/docs/design/README.md
index 27b85695cd474..f0aa9c766a44c 100644
--- a/docs/design/README.md
+++ b/docs/design/README.md
@@ -301,23 +301,21 @@ Some common expressions in Carbon include:
 ### Functions
 
 > References: [Functions](functions.md)
->
-> **TODO:** References need to be evolved.
 
 Functions are the core unit of behavior. For example:
 
 ```carbon
-fn Sum(a: Int, b: Int) -> Int;
+fn Add(a: i64, b: i64) -> i64;
 ```
 
 Breaking this apart:
 
 -   `fn` is the keyword used to indicate a function.
--   Its name is `Sum`.
--   It accepts two `Int` parameters, `a` and `b`.
--   It returns an `Int` result.
+-   Its name is `Add`.
+-   It accepts two `i64` parameters, `a` and `b`.
+-   It returns an `i64` result.
 
-You would call this function like `Sum(1, 2)`.
+You would call this function like `Add(1, 2)`.
 
 ### Blocks and statements
 
@@ -354,8 +352,8 @@ work similarly to function parameters.
 For example:
 
 ```carbon
-fn Foo() {
-  var x: Int = 42;
+fn DoSomething() {
+  var x: i64 = 42;
 }
 ```
 
@@ -363,7 +361,7 @@ Breaking this apart:
 
 -   `var` is the keyword used to indicate a variable.
 -   Its name is `x`.
--   Its type is `Int`.
+-   Its type is `i64`.
 -   It is initialized with the value `42`.
 
 ### Lifetime and move semantics

From 3fde0cf38760b156e3ad9b5fc73485b63d93e902 Mon Sep 17 00:00:00 2001
From: jonmeow <46229924+jonmeow@users.noreply.github.com>
Date: Wed, 12 Jan 2022 18:15:25 +0000
Subject: [PATCH 04/16] Address comments

---
 docs/design/functions.md      | 9 +++++++++
 docs/design/type_inference.md | 6 ++++--
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/docs/design/functions.md b/docs/design/functions.md
index 13ea09d904f30..307d63a642377 100644
--- a/docs/design/functions.md
+++ b/docs/design/functions.md
@@ -145,6 +145,15 @@ Here, `Add(1, 2)` is a function call expression. `Add` refers to the function
 definition's identifier. The parenthesized arguments `(1, 2)` are passed to the
 `a` and `b` parameters of `Add`.
 
+## Advanced functions
+
+Other designs build upon basic function syntax to add advanced features:
+
+-   [Generic functions](generics/overview.md#generic-functions) adds support for
+    deduced parameters and generic type parameters.
+-   [Class member functions](classes.md#member-functions) adds support for
+    methods and class functions.
+
 ## Alternatives considered
 
 -   [Function keyword](/proposals/p0438.md#function-keyword)
diff --git a/docs/design/type_inference.md b/docs/design/type_inference.md
index 984ac73f52af0..599eced4da135 100644
--- a/docs/design/type_inference.md
+++ b/docs/design/type_inference.md
@@ -38,8 +38,10 @@ and [declared variable types](variables.md).
 
 Using the type on the right side for `var y: auto = 1` currently results in a
 constant `IntLiteral(1)` value, whereas most languages would suggest a variable
-integer type, such as `i64`. This is a temporary choice due to the lack of a
-more complete design, and is open to change in the future.
+integer type, such as `i64`. Carbon might also make it an error. Although type
+inference currently only addresses `auto` for variables and function return
+types, this is something that will be considered as part of type inference in
+general, because it also affects generics, templates, lambdas, and return types.
 
 ## Alternatives considered
 

From 0fa6969195b05ce910bfe7c6806d2e97b32c1858 Mon Sep 17 00:00:00 2001
From: jonmeow <46229924+jonmeow@users.noreply.github.com>
Date: Wed, 12 Jan 2022 18:15:35 +0000
Subject: [PATCH 05/16] Address comments

---
 docs/design/functions.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/design/functions.md b/docs/design/functions.md
index 307d63a642377..eb4099f0680a5 100644
--- a/docs/design/functions.md
+++ b/docs/design/functions.md
@@ -16,6 +16,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
     -   [`return` statements](#return-statements)
 -   [Function declarations](#function-declarations)
 -   [Function calls](#function-calls)
+-   [Advanced functions](#advanced-functions)
 -   [Alternatives considered](#alternatives-considered)
 -   [References](#references)
 

From 44aa290a31acb6697a17cb486e3261038b274fe3 Mon Sep 17 00:00:00 2001
From: jonmeow <46229924+jonmeow@users.noreply.github.com>
Date: Wed, 12 Jan 2022 19:18:27 +0000
Subject: [PATCH 06/16] arg->parameter

---
 docs/design/functions.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/design/functions.md b/docs/design/functions.md
index eb4099f0680a5..8d82e1ebbfa2b 100644
--- a/docs/design/functions.md
+++ b/docs/design/functions.md
@@ -27,10 +27,10 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 Functions are the core building block for applications. Carbon's basic function
 syntax is:
 
--   _arg#_: _identifier_ `:` _expression_
+-   _parameter_: _identifier_ `:` _expression_
+-   _parameter-list_: _[ parameter_ `,` _parameter_ `,` _... ]_
 -   _return-clause_: _[_ `->` _< expression |_ `auto` _> ]_
--   _signature_: `fn` _identifier_ `(` _[ arg1_ `,` _arg2_ `,` _... ]_ `)`
-    _return-clause_
+-   _signature_: `fn` _identifier_ `(` _parameter-list_ `)` _return-clause_
 -   _function-definition_: _signature_ `{` _statements_ `}`
 -   _function-declaration_: _signature_ `;`
 -   _function-call_: _identifier_ `(` _[ expression_ `,` _expression_ `,` _...

From 2e3dcc4071ac31b86aba804879ded73a29d6327f Mon Sep 17 00:00:00 2001
From: jonmeow <46229924+jonmeow@users.noreply.github.com>
Date: Thu, 20 Jan 2022 22:24:23 +0000
Subject: [PATCH 07/16] Addressing comments

---
 docs/design/functions.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/design/functions.md b/docs/design/functions.md
index 8d82e1ebbfa2b..6f20ffdf41da7 100644
--- a/docs/design/functions.md
+++ b/docs/design/functions.md
@@ -87,9 +87,9 @@ possible syntaxes:
     -   The function must have precisely one `return` statement. That `return`
         statement's expression will then be used for type inference.
 -   Omission indicates that the return type is the empty tuple, `()`.
-    -   For example, `fn Sleep(seconds: i64);` is equivalent to
+    -   For example, `fn Sleep(seconds: i64);` is similar to
         `fn Sleep(seconds: i64) -> ();`.
-    -   This is similar to a `void` return in C++.
+    -   `()` is similar to a `void` return type in C++.
 
 ### `return` statements
 
@@ -130,7 +130,7 @@ contain a function's declaration while the `impl` file contains the definition.
 ## Function calls
 
 Function calls use a function's identifier to pass multiple expression arguments
-in place of parameters. For example:
+corresponding to the function signature's parameters. For example:
 
 ```carbon
 fn Add(a: i64, b: i64) -> i64 {
@@ -146,7 +146,7 @@ Here, `Add(1, 2)` is a function call expression. `Add` refers to the function
 definition's identifier. The parenthesized arguments `(1, 2)` are passed to the
 `a` and `b` parameters of `Add`.
 
-## Advanced functions
+## Functions in other features
 
 Other designs build upon basic function syntax to add advanced features:
 

From e295850bed5ca907ee4eb27333aa587b9eeae006 Mon Sep 17 00:00:00 2001
From: jonmeow <46229924+jonmeow@users.noreply.github.com>
Date: Thu, 20 Jan 2022 22:24:32 +0000
Subject: [PATCH 08/16] Addressing comments

---
 docs/design/functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/design/functions.md b/docs/design/functions.md
index 6f20ffdf41da7..55677cce51338 100644
--- a/docs/design/functions.md
+++ b/docs/design/functions.md
@@ -16,7 +16,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
     -   [`return` statements](#return-statements)
 -   [Function declarations](#function-declarations)
 -   [Function calls](#function-calls)
--   [Advanced functions](#advanced-functions)
+-   [Functions in other features](#functions-in-other-features)
 -   [Alternatives considered](#alternatives-considered)
 -   [References](#references)
 

From 4394fac5e3120085ca22927e2f85c10bf99fbd3f Mon Sep 17 00:00:00 2001
From: Jon Meow <46229924+jonmeow@users.noreply.github.com>
Date: Thu, 27 Jan 2022 12:57:32 -0800
Subject: [PATCH 09/16] Update docs/design/variables.md

Co-authored-by: Chandler Carruth <chandlerc@gmail.com>
---
 docs/design/variables.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/design/variables.md b/docs/design/variables.md
index ed8bea30dbdd1..8eb290e1781ac 100644
--- a/docs/design/variables.md
+++ b/docs/design/variables.md
@@ -22,7 +22,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 Carbon's local variable syntax is:
 
--   `var` _identifier_`:` _< expression |_ `auto` _> [_ `=` _value_ _]_`;`
+-   `var` _identifier_`:` _< expression |_ `auto` _> [_ `=` _value ]_`;`
 
 Blocks introduce nested scopes and can contain local variable declarations that
 work similarly to function parameters.

From 3b4242a03847a8acfba0cf451651db9612ccd698 Mon Sep 17 00:00:00 2001
From: jonmeow <46229924+jonmeow@users.noreply.github.com>
Date: Thu, 27 Jan 2022 21:11:24 +0000
Subject: [PATCH 10/16] Rephrasing  statements.

---
 docs/design/functions.md | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/docs/design/functions.md b/docs/design/functions.md
index 55677cce51338..7ff5c2090dd4d 100644
--- a/docs/design/functions.md
+++ b/docs/design/functions.md
@@ -95,10 +95,15 @@ possible syntaxes:
 
 The [`return` statement](control_flow/return.md) is essential to function
 control flow. It ends the flow of the function and returns execution to the
-caller. The `return` statement must be used to end control flow of a function
-when a non-empty [return clause](#return-clause) is used. A `return` statement
-must have an expression argument if and only if there is a non-empty return
-clause.
+caller.
+
+When the [return clause](#return-clause) is omitted, the `return` statement has
+no expression argument, and function control flow implicitly ends after the last
+statement in the function's body as if `return;` were present.
+
+When the return clause is provided, including when it is `-> ()`, the `return`
+statement must have an expression that is convertible to the return type, and a
+`return` statement must be used to end control flow of the function.
 
 ## Function declarations
 

From b691a56b1594cf4a315d813e694a193acc57bcb6 Mon Sep 17 00:00:00 2001
From: Jon Meow <46229924+jonmeow@users.noreply.github.com>
Date: Fri, 28 Jan 2022 10:10:08 -0800
Subject: [PATCH 11/16] Update docs/design/functions.md

Co-authored-by: Richard Smith <richard@metafoo.co.uk>
---
 docs/design/functions.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/design/functions.md b/docs/design/functions.md
index 7ff5c2090dd4d..a32b3f6b3819e 100644
--- a/docs/design/functions.md
+++ b/docs/design/functions.md
@@ -38,8 +38,7 @@ syntax is:
 
 A function with only a signature and no body is a function declaration, or
 forward declaration. When the body is a present, it's a function definition. The
-body introduces nested scopes which may contain local local variable
-declarations.
+body introduces nested scopes which may contain local variable declarations.
 
 ## Function definitions
 

From 2a5c8c4ea628d19dfaeac9bc642f0ccf2e004a26 Mon Sep 17 00:00:00 2001
From: Jon Meow <46229924+jonmeow@users.noreply.github.com>
Date: Fri, 28 Jan 2022 10:10:22 -0800
Subject: [PATCH 12/16] Update docs/design/functions.md

Co-authored-by: Richard Smith <richard@metafoo.co.uk>
---
 docs/design/functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/design/functions.md b/docs/design/functions.md
index a32b3f6b3819e..4b680c66152a5 100644
--- a/docs/design/functions.md
+++ b/docs/design/functions.md
@@ -147,7 +147,7 @@ fn Main() {
 ```
 
 Here, `Add(1, 2)` is a function call expression. `Add` refers to the function
-definition's identifier. The parenthesized arguments `(1, 2)` are passed to the
+definition's identifier. The parenthesized arguments `1` and `2` are passed to the
 `a` and `b` parameters of `Add`.
 
 ## Functions in other features

From 7efd3cc283acb71ae407a6904e78a83514e0a11c Mon Sep 17 00:00:00 2001
From: Jon Meow <46229924+jonmeow@users.noreply.github.com>
Date: Fri, 28 Jan 2022 10:10:42 -0800
Subject: [PATCH 13/16] Update docs/design/variables.md

Co-authored-by: Richard Smith <richard@metafoo.co.uk>
---
 docs/design/variables.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/design/variables.md b/docs/design/variables.md
index 8eb290e1781ac..ec882c5e2e771 100644
--- a/docs/design/variables.md
+++ b/docs/design/variables.md
@@ -40,9 +40,9 @@ type `Int` and is initialized with the value `42`. These variable declarations
 (and function declarations) have a lot more power than what we're covering just
 yet, but this gives you the basic idea.
 
-If `auto` is used in place of the type, it will use
-[type inference](type_inference.md) to automatically determine the variable
-type.
+If `auto` is used in place of the type,
+[type inference](type_inference.md) is used to automatically determine the
+variable's type.
 
 While there can be global constants, there are no global variables.
 

From a019c9c2a64098d97d2c8e100c93c1351e04c104 Mon Sep 17 00:00:00 2001
From: jonmeow <46229924+jonmeow@users.noreply.github.com>
Date: Fri, 28 Jan 2022 19:12:31 +0000
Subject: [PATCH 14/16] Remove paragraph

---
 docs/design/functions.md | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/docs/design/functions.md b/docs/design/functions.md
index 4b680c66152a5..907db35e6c37b 100644
--- a/docs/design/functions.md
+++ b/docs/design/functions.md
@@ -127,10 +127,6 @@ corresponding definition. This includes the [return clause](#return-clause);
 even though an omitted return type has equivalent behavior to `-> ()`, the
 presence or omission must match.
 
-A function declaration can be called, and the function definition may be
-provided later in code; for example, the `api` file of a library will often
-contain a function's declaration while the `impl` file contains the definition.
-
 ## Function calls
 
 Function calls use a function's identifier to pass multiple expression arguments

From b959388c69383f3656ac0125e6b1d59c78b88728 Mon Sep 17 00:00:00 2001
From: jonmeow <46229924+jonmeow@users.noreply.github.com>
Date: Fri, 28 Jan 2022 19:12:49 +0000
Subject: [PATCH 15/16] prettier

---
 docs/design/functions.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/design/functions.md b/docs/design/functions.md
index 907db35e6c37b..8d20135b5e3e5 100644
--- a/docs/design/functions.md
+++ b/docs/design/functions.md
@@ -143,8 +143,8 @@ fn Main() {
 ```
 
 Here, `Add(1, 2)` is a function call expression. `Add` refers to the function
-definition's identifier. The parenthesized arguments `1` and `2` are passed to the
-`a` and `b` parameters of `Add`.
+definition's identifier. The parenthesized arguments `1` and `2` are passed to
+the `a` and `b` parameters of `Add`.
 
 ## Functions in other features
 

From e6d499df92fbb1968c6cfdd5ddf0a8777960e715 Mon Sep 17 00:00:00 2001
From: jonmeow <46229924+jonmeow@users.noreply.github.com>
Date: Fri, 28 Jan 2022 19:13:33 +0000
Subject: [PATCH 16/16] prettier

---
 docs/design/variables.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/docs/design/variables.md b/docs/design/variables.md
index ec882c5e2e771..109f522a3d0bd 100644
--- a/docs/design/variables.md
+++ b/docs/design/variables.md
@@ -40,9 +40,8 @@ type `Int` and is initialized with the value `42`. These variable declarations
 (and function declarations) have a lot more power than what we're covering just
 yet, but this gives you the basic idea.
 
-If `auto` is used in place of the type,
-[type inference](type_inference.md) is used to automatically determine the
-variable's type.
+If `auto` is used in place of the type, [type inference](type_inference.md) is
+used to automatically determine the variable's type.
 
 While there can be global constants, there are no global variables.