carbon-language · jonmeow · Jul 30, 2020 · May 20, 2020 · May 20, 2020 · May 21, 2020
diff --git a/docs/design/README.md b/docs/design/README.md
diff --git a/docs/design/aliases.md b/docs/design/aliases.md
@@ -10,9 +10,9 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 <!-- toc -->
 
-- [TODO](#todo)
-- [Overview](#overview)
-  - [Alternatives](#alternatives)
+-   [TODO](#todo)
+-   [Overview](#overview)
+    -   [Alternatives](#alternatives)
 
 <!-- tocstop -->
 

diff --git a/docs/design/blocks_and_statements.md b/docs/design/blocks_and_statements.md
@@ -10,8 +10,8 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 <!-- toc -->
 
-- [TODO](#todo)
-- [Overview](#overview)
+-   [TODO](#todo)
+-   [Overview](#overview)
 
 <!-- tocstop -->
 

diff --git a/docs/design/control_flow.md b/docs/design/control_flow.md
@@ -10,11 +10,11 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 <!-- toc -->
 
-- [TODO](#todo)
-- [Overview](#overview)
-- [Open questions](#open-questions)
-  - [`if` blocks](#if-blocks)
-  - [`break` and `continue`](#break-and-continue)
+-   [TODO](#todo)
+-   [Overview](#overview)
+-   [Open questions](#open-questions)
+    -   [`if` blocks](#if-blocks)
+    -   [`break` and `continue`](#break-and-continue)
 
 <!-- tocstop -->
 
@@ -50,7 +50,7 @@ fn Foo(Int: x) {
 }
 ```
 
-Loops will at least be supported with a low-level primitive `loop` statement,
+Loops will at least be supported with a low-level primitive `while` statement,
 with `break` and `continue` statements which work the same as in C++.
 
 Last but not least, for the basics we need to include the `return` statement.

diff --git a/docs/design/files_libraries_and_packages.md b/docs/design/files_libraries_and_packages.md
@@ -10,9 +10,9 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 <!-- toc -->
 
-- [TODO](#todo)
-- [Alternatives](#alternatives)
-  - [File extensions](#file-extensions)
+-   [TODO](#todo)
+-   [Alternatives](#alternatives)
+    -   [File extensions](#file-extensions)
 
 <!-- tocstop -->
 
@@ -31,12 +31,12 @@ The use of `6c` as a short file extension or top-level CLI (with subcommands
 below it similar to `git` or `go`) has some drawbacks. There are several other
 possible extensions / commands:
 
-- `cb`: This collides with several acronyms and may not be especially memorable
-  as referring to Carbon.
-- `c6`: This seems a weird incorrect ordering of the atomic number and has a bad
-  (if _extremely_ obscure) Internet slang association (NSFW, use caution if
-  searching, as with too much Internet slang).
-- `carbon`: This is an obvious and unsurprising choice, but also quite long.
+-   `cb`: This collides with several acronyms and may not be especially
+    memorable as referring to Carbon.
+-   `c6`: This seems a weird incorrect ordering of the atomic number and has a
+    bad (if _extremely_ obscure) Internet slang association (NSFW, use caution
+    if searching, as with too much Internet slang).
+-   `carbon`: This is an obvious and unsurprising choice, but also quite long.
 
 This seems fairly easy for us to change as we go along, but we should at some
 point do a formal proposal to gather other options and let the core team try to

diff --git a/docs/design/functions.md b/docs/design/functions.md
@@ -10,8 +10,8 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 <!-- toc -->
 
-- [TODO](#todo)
-- [Basic functions](#basic-functions)
+-   [TODO](#todo)
+-   [Basic functions](#basic-functions)
 
 <!-- tocstop -->
 

diff --git a/docs/design/interoperability/template.md → docs/design/interoperability/README.md b/docs/design/interoperability/template.md → docs/design/interoperability/README.md
@@ -1,4 +1,4 @@
-# Carbon ↔ C/C++ interoperability
+# Bidirectional interoperability with C/C++
 
 <!--
 Part of the Carbon Language project, under the Apache License v2.0 with LLVM
@@ -10,8 +10,8 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 <!-- toc -->
 
-- [TODO](#todo)
-- [Overview](#overview)
+-   [TODO](#todo)
+-   [Overview](#overview)
 
 <!-- tocstop -->
 

diff --git a/docs/design/lexical_conventions.md b/docs/design/lexical_conventions.md
@@ -10,7 +10,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 <!-- toc -->
 
-- [TODO](#todo)
+-   [TODO](#todo)
 
 <!-- tocstop -->
 

diff --git a/docs/design/metaprogramming.md b/docs/design/metaprogramming.md
@@ -10,8 +10,8 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 <!-- toc -->
 
-- [TODO](#todo)
-- [Overview](#overview)
+-   [TODO](#todo)
+-   [Overview](#overview)
 
 <!-- tocstop -->
 
@@ -22,6 +22,10 @@ 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.
 
+See
+[carbon-proposals PR 89](https://github.com/carbon-language/carbon-proposals/pull/89)
+for context -- that proposal may replace this.
+
 ## Overview
 
 Carbon provides metaprogramming facilities that look similar to regular Carbon

diff --git a/docs/design/name_lookup.md b/docs/design/name_lookup.md
@@ -10,13 +10,13 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 <!-- toc -->
 
-- [TODO](#todo)
-- [Overview](#overview)
-  - [Unqualified name lookup](#unqualified-name-lookup)
-    - [Alternatives](#alternatives)
-  - [Name lookup for common, standard types](#name-lookup-for-common-standard-types)
-- [Open questions](#open-questions)
-  - [Shadowing](#shadowing)
+-   [TODO](#todo)
+-   [Overview](#overview)
+    -   [Unqualified name lookup](#unqualified-name-lookup)
+        -   [Alternatives](#alternatives)
+    -   [Name lookup for common, standard types](#name-lookup-for-common-standard-types)
+-   [Open questions](#open-questions)
+    -   [Shadowing](#shadowing)
 
 <!-- tocstop -->
 
@@ -75,12 +75,13 @@ the package scope for unqualified name lookup.
 ### Name lookup for common, standard types
 
 The Carbon standard library is in the `Carbon` package. A very small subset of
-this standard library is provided implicitly in every file's scope as-if it were
-first imported and then every name in it aliased into that file's package scope.
-This makes the names from this part of the standard library nearly the same as
-keywords, and so it is expected to be extremely small but contain the very
-fundamentals that essentially every file of Carbon code will need (`Int`,
-`Bool`, etc.).
+this standard library is provided implicitly in every file's scope. This is
+called the "prelude" package.
+
+Names in the prelude package will be available without scoping names. For
+example, `Bool` will be the commonly used name in code, even though the
+underlying type may be `Carbon::Bool`. Also, no `import` will be necessary to
+use `Bool`.
 
 ## Open questions
 

diff --git a/docs/design/naming_conventions.md b/docs/design/naming_conventions.md
@@ -10,8 +10,8 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 <!-- toc -->
 
-- [TODO](#todo)
-- [Overview](#overview)
+-   [TODO](#todo)
+-   [Overview](#overview)
 
 <!-- tocstop -->
 
@@ -34,13 +34,14 @@ Our current proposed naming convention, which we at least are attempting to
 follow within Carbon documentation in order to keep code samples as consistent
 as possible, is:
 
-- `UpperCamelCase` for names of compile-time resolved constants, such that they
-  can participate in the type system and type checking of the program.
-  Comple-time constants fall into two categories:
-  - _Template_ constants that can be used in type checking, including literals.
-  - _Generic_ constants whose value is not used in type checking, but will be
-    used as part of code generation.
-- `lower_snake_case` for names of run-time resolved values.
+-   `UpperCamelCase` for names of compile-time resolved constants, such that
+    they can participate in the type system and type checking of the program.
+    Comple-time constants fall into two categories:
+    -   _Template_ constants that can be used in type checking, including
+        literals.
+    -   _Generic_ constants whose value is not used in type checking, but will
+        be used as part of code generation.
+-   `lower_snake_case` for names of run-time resolved values.
 
 As an example, an integer that is a compile-time constant sufficient to use in
 the construction a compile-time array size might be named `N`, where an integer

diff --git a/docs/design/operators.md b/docs/design/operators.md
@@ -10,7 +10,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 <!-- toc -->
 
-- [TODO](#todo)
+-   [TODO](#todo)
 
 <!-- tocstop -->
 

diff --git a/docs/design/pattern_matching.md b/docs/design/pattern_matching.md
@@ -10,14 +10,14 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 <!-- toc -->
 
-- [TODO](#todo)
-- [Overview](#overview)
-  - [Pattern match control flow](#pattern-match-control-flow)
-  - [Pattern matching in local variables](#pattern-matching-in-local-variables)
-- [Open questions](#open-questions)
-  - [Slice or array nested value pattern matching](#slice-or-array-nested-value-pattern-matching)
-  - [Generic/template pattern matching](#generictemplate-pattern-matching)
-  - [Pattern matching as function overload resolution](#pattern-matching-as-function-overload-resolution)
+-   [TODO](#todo)
+-   [Overview](#overview)
+    -   [Pattern match control flow](#pattern-match-control-flow)
+    -   [Pattern matching in local variables](#pattern-matching-in-local-variables)
+-   [Open questions](#open-questions)
+    -   [Slice or array nested value pattern matching](#slice-or-array-nested-value-pattern-matching)
+    -   [Generic/template pattern matching](#generictemplate-pattern-matching)
+    -   [Pattern matching as function overload resolution](#pattern-matching-as-function-overload-resolution)
 
 <!-- tocstop -->
 
@@ -75,15 +75,15 @@ introduced by the `if` keyword. The value pattern has to match, and then the
 predicate has to evaluate to true for the overall pattern to match. Value
 patterns can be composed of the following:
 
-- An expression (`42` for example), whose value must be equal to match.
-- An optional type (`Int` for example), followed by a `:` and either an
-  identifier to bind to the value or the special identifier `_` to discard the
-  value once matched.
-- A destructuring pattern containing a sequence of value patterns
-  (`(Float: x, Float: y)`) which match against tuples and tuple like values by
-  recursively matching on their elements.
-- An unwrapping pattern containing a nested value pattern which matches against
-  a variant or variant-like value by unwrapping it.
+-   An expression (`42` for example), whose value must be equal to match.
+-   An optional type (`Int` for example), followed by a `:` and either an
+    identifier to bind to the value or the special identifier `_` to discard the
+    value once matched.
+-   A destructuring pattern containing a sequence of value patterns
+    (`(Float: x, Float: y)`) which match against tuples and tuple like values by
+    recursively matching on their elements.
+-   An unwrapping pattern containing a nested value pattern which matches
+    against a variant or variant-like value by unwrapping it.
 
 In order to match a value, whatever is specified in the pattern must match.
 Using `auto` for a type will always match, making `auto: _` the wildcard

diff --git a/docs/design/primitive_types.md b/docs/design/primitive_types.md
@@ -10,16 +10,16 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 <!-- toc -->
 
-- [TODO](#todo)
-- [Overview](#overview)
-  - [Integers](#integers)
-  - [Floats](#floats)
-  - [BFloat16](#bfloat16)
-- [Open questions](#open-questions)
-  - [Primitive types as code vs built-in](#primitive-types-as-code-vs-built-in)
-  - [String view vs owning string](#string-view-vs-owning-string)
-  - [Syntax for wrapping operations](#syntax-for-wrapping-operations)
-  - [Non-power-of-two sizes](#non-power-of-two-sizes)
+-   [TODO](#todo)
+-   [Overview](#overview)
+    -   [Integers](#integers)
+    -   [Floats](#floats)
+    -   [BFloat16](#bfloat16)
+-   [Open questions](#open-questions)
+    -   [Primitive types as code vs built-in](#primitive-types-as-code-vs-built-in)
+    -   [String view vs owning string](#string-view-vs-owning-string)
+    -   [Syntax for wrapping operations](#syntax-for-wrapping-operations)
+    -   [Non-power-of-two sizes](#non-power-of-two-sizes)
 
 <!-- tocstop -->
 
@@ -34,19 +34,22 @@ update as appropriate.
 
 These types are fundamental to the language as they aren't either formed from or
 modifying other types. They also have semantics that are defined from first
-principles rather than in terms of other operations. Even though these are
-special, their names are not keywords or reserved; they are just names in the
-implicit "prelude" that is imported and aliased into all files.
-
-They in turn can be decomposed into the following categories:
-
-- A monotype `Void` (or possibly `()`, the empty tuple) that has only one
-  possible value (empty).
-- A boolean type `Bool` that has two possible values: `True` and `False`.
-- Integer types
-- Floating point types
-- A string view type which is a read-only reference to a sequence of bytes
-  typically representing (UTF-8 encoded) text.
+principles rather than in terms of other operations. These will be made
+available through the [prelude package](README.md#name-lookup-for-common-types).
+
+-   `Void` - a type with only one possible value: empty.
+-   `Bool` - a boolean type with two possible values: `True` and `False`.
+-   `Int` and `UInt` - signed and unsigned 64-bit integer types.
+    -   Standard sizes are available, both signed and unsigned, including
+        `Int8`, `Int16`, `Int32`, `Int128`, and `Int256`.
+    -   Overflow in either direction is an error.
+-   `Float64` - a floating point type with semantics based on IEEE-754.
+    -   Standard sizes are available, including `Float16`, `Float32`, and
+        `Float128`.
+    -   [`BFloat16`](primitive_types.md#bfloat16) is also provided.
+-   `String` - a byte sequence treated as containing UTF-8 encoded text.
+    -   `StringView` - a read-only reference to a byte sequence treated as
+        containing UTF-8 encoded text.
 
 ### Integers
 

diff --git a/docs/design/structs.md b/docs/design/structs.md
@@ -10,11 +10,11 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 <!-- toc -->
 
-- [TODO](#todo)
-- [Overview](#overview)
-- [Open questions](#open-questions)
-  - [`self` type](#self-type)
-  - [Default access control level](#default-access-control-level)
+-   [TODO](#todo)
+-   [Overview](#overview)
+-   [Open questions](#open-questions)
+    -   [`self` type](#self-type)
+    -   [Default access control level](#default-access-control-level)
 
 <!-- tocstop -->
 
@@ -84,10 +84,10 @@ the type.
 
 Some things in C++ are notably absent or orthogonally handled:
 
-- No need for `static` functions, they simply don't take an initial `self`
-  parameter.
-- No `static` variables because there are no global variables. Instead, can have
-  scoped constants.
+-   No need for `static` functions, they simply don't take an initial `self`
+    parameter.
+-   No `static` variables because there are no global variables. Instead, can
+    have scoped constants.
 
 ## Open questions
 

diff --git a/docs/design/syntactic_conventions.md b/docs/design/syntactic_conventions.md
@@ -10,10 +10,10 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 <!-- toc -->
 
-- [TODO](#todo)
-- [Overview](#overview)
-- [Alternatives](#alternatives)
-  - [Types before or after name](#types-before-or-after-name)
+-   [TODO](#todo)
+-   [Overview](#overview)
+-   [Alternatives](#alternatives)
+    -   [Types before or after name](#types-before-or-after-name)
 
 <!-- tocstop -->