Mark what is provisional in the design overview (#1984)

Also references were added to clarify that some features are not provisional.

Co-authored-by: Jon Ross-Perkins <[email protected]>
Co-authored-by: Geoff Romer <[email protected]>

docs/design/README.md

@@ -6,6 +6,9 @@ Exceptions. See /LICENSE for license information.
 SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 -->
 
+> **STATUS:** Up-to-date on 09-Aug-2022, including proposals up through
+> [#1327](https://github.com/carbon-language/carbon-lang/pull/1327).
+
 <!-- toc -->
 
 ## Table of contents
@@ -134,6 +137,7 @@ This document includes much that is provisional or placeholder. This means that
 the syntax used, language rules, standard library, and other aspects of the
 design have things that have not been decided through the Carbon process. This
 preliminary material fills in gaps until aspects of the design can be filled in.
+Features that are provisional have been marked as such on a best-effort basis.
 
 ## Hello, Carbon
 
@@ -347,6 +351,9 @@ selected.
 
 ### String types
 
+> **Note:** This is provisional, no design for string types has been through the
+> proposal process yet.
+
 There are two string types:
 
 -   `String` - a byte sequence treated as containing UTF-8 encoded text.
@@ -390,9 +397,6 @@ are available for representing strings with `\`s and `"`s.
 
 ## Value categories and value phases
 
-**FIXME:** Should this be moved together with
-[Types are values](#types-are-values)?
-
 Every value has a
 [value category](<https://en.wikipedia.org/wiki/Value_(computer_science)#lrvalue>),
 similar to [C++](https://en.cppreference.com/w/cpp/language/value_category),
@@ -435,6 +439,10 @@ generally convert into runtime values if an operation that inspects the value is
 performed on them. Runtime values will convert into constants or to symbolic
 values if constant evaluation of the runtime expression succeeds.
 
+> **Note:** Conversion of runtime values to other phases is provisional, as are
+> the semantics of r-values. See pending proposal
+> [#821: Values, variables, pointers, and references](https://github.com/carbon-language/carbon-lang/pull/821).
+
 ## Composite types
 
 ### Tuples
@@ -471,6 +479,10 @@ fn DoubleTuple(x: (i32, i32)) -> (i32, i32) {
 Tuple types are
 [structural](https://en.wikipedia.org/wiki/Structural_type_system).
 
+> **Note:** This is provisional, no design for tuples has been through the
+> proposal process yet. Many of these questions were discussed in dropped
+> proposal [#111](https://github.com/carbon-language/carbon-lang/pull/111).
+
 > References: [Tuples](tuples.md)
 
 ### Struct types
@@ -521,6 +533,10 @@ type `Optional(T*)`.
 [stricter pointer provenance](https://www.ralfj.de/blog/2022/04/11/provenance-exposed.html)
 or restrictions on casts between pointers and integers.
 
+> **Note:** While the syntax for pointers has been decided, the semantics of
+> pointers are provisional, as is the syntax for optionals. See pending proposal
+> [#821: Values, variables, pointers, and references](https://github.com/carbon-language/carbon-lang/pull/821).
+
 > References:
 >
 > -   Question-for-leads issue
@@ -552,6 +568,10 @@ Console.Print(a[0]);
 
 > **TODO:** Slices
 
+> **Note:** This is provisional, no design for arrays has been through the
+> proposal process yet. See pending proposal
+> [#1928: Arrays](https://github.com/carbon-language/carbon-lang/pull/1928).
+
 ## Expressions
 
 Expressions describe some computed value. The simplest example would be a
@@ -654,6 +674,9 @@ function or class itself is visible until the end of the enclosing scope.
 
 ## Patterns
 
+> **Note:** This is provisional, no design for patterns has been through the
+> proposal process yet.
+
 A _pattern_ says how to receive some data that is being matched against. There
 are two kinds of patterns:
 
@@ -782,6 +805,9 @@ Here `x: i64` is the pattern, which is followed by an equal sign (`=`) and the
 value to match, `42`. The names from [binding patterns](#binding-patterns) are
 introduced into the enclosing [scope](#declarations-definitions-and-scopes).
 
+> **Note:** `let` declarations are provisional. See pending proposal
+> [#821: Values, variables, pointers, and references](https://github.com/carbon-language/carbon-lang/pull/821).
+
 ### Variable `var` declarations
 
 A `var` declaration is similar, except with `var` bindings, so `x` here is an
@@ -897,6 +923,10 @@ the caller, and dereferencing using `*` in the callee.
 Outputs of a function should prefer to be returned. Multiple values may be
 returned using a [tuple](#tuples) or [struct](#struct-types) type.
 
+> **Note:** The semantics of parameter passing are provisional. See pending
+> proposal
+> [#821: Values, variables, pointers, and references](https://github.com/carbon-language/carbon-lang/pull/821).
+
 ### `auto` return type
 
 If `auto` is used in place of the return type, the return type of the function
@@ -967,6 +997,9 @@ the assignment.
 Unlike C++, these assignments are statements, not expressions, and don't return
 a value.
 
+> **Note:** The semantics of assignment are provisional. See pending proposal
+> [#821: Values, variables, pointers, and references](https://github.com/carbon-language/carbon-lang/pull/821).
+
 ### Control flow
 
 Blocks of statements are generally executed sequentially. Control-flow
@@ -1093,7 +1126,13 @@ for (var step: Step in steps) {
 }
 ```
 
-> References: [`break`](control_flow/loops.md#break)
+> References:
+>
+> -   [`break`](control_flow/loops.md#break)
+> -   Proposal
+>     [#340: Add C++-like `while` loops](https://github.com/carbon-language/carbon-lang/pull/340)
+> -   Proposal
+>     [#353: Add C++-like `for` loops](https://github.com/carbon-language/carbon-lang/pull/353)
 
 ##### `continue`
 
@@ -1113,7 +1152,13 @@ while (!f.EOF()) {
 }
 ```
 
-> References: [`continue`](control_flow/loops.md#continue)
+> References:
+>
+> -   [`continue`](control_flow/loops.md#continue)
+> -   Proposal
+>     [#340: Add C++-like `while` loops](https://github.com/carbon-language/carbon-lang/pull/340)
+> -   Proposal
+>     [#353: Add C++-like `for` loops](https://github.com/carbon-language/carbon-lang/pull/353)
 
 #### `return`
 
@@ -1223,6 +1268,9 @@ fn Foo() -> f32 {
 }
 ```
 
+> **Note:** This is provisional, no design for `match` statements has been
+> through the proposal process yet.
+
 > References:
 >
 > -   [Pattern matching](pattern_matching.md)
@@ -1231,8 +1279,6 @@ fn Foo() -> f32 {
 
 ## User-defined types
 
-> **TODO:** Maybe rename to "nominal types"?
-
 ### Classes
 
 _Nominal classes_, or just
@@ -1316,7 +1362,9 @@ sprocket = {.x = 2, .y = 1, .payload = "Bounce"};
 
 > References:
 >
-> -   [Classes: Construction](classes.md#construction)
+> -   [Classes: Assignment](classes.md#assignment)
+> -   Proposal
+>     [#722: Nominal classes and methods](https://github.com/carbon-language/carbon-lang/pull/722)
 > -   Proposal
 >     [#981: Implicit conversions for aggregates](https://github.com/carbon-language/carbon-lang/pull/981)
 
@@ -1364,6 +1412,12 @@ class Registered {
 
 This approach can also be used for types that can't be copied or moved.
 
+> References:
+>
+> -   [Classes: Construction](classes.md#construction)
+> -   Proposal
+>     [#722: Nominal classes and methods](https://github.com/carbon-language/carbon-lang/pull/722)
+
 #### Methods
 
 Class type definitions can include methods:
@@ -1522,7 +1576,7 @@ class DerivedFromAbstract extends AbstractClass {
 
 > References:
 >
-> -   [Inheritance](classes.md#inheritance)
+> -   [Classes: Inheritance](classes.md#inheritance)
 > -   Proposal
 >     [#777: Inheritance](https://github.com/carbon-language/carbon-lang/pull/777)
 > -   Proposal
@@ -1546,6 +1600,8 @@ names resolvable by the compiler, and don't act like forward declarations.
 > -   [Access control for class members](classes.md#access-control)
 > -   Question-for-leads issue
 >     [#665: `private` vs `public` _syntax_ strategy, as well as other visibility tools like `external`/`api`/etc.](https://github.com/carbon-language/carbon-lang/issues/665)
+> -   Proposal
+>     [#777: Inheritance](https://github.com/carbon-language/carbon-lang/pull/777)
 > -   Question-for-leads issue
 >     [#971: Private interfaces in public API files](https://github.com/carbon-language/carbon-lang/issues/971)
 
@@ -1585,14 +1641,14 @@ type, use `UnsafeDelete`.
 
 > References:
 >
-> -   [Destructors](classes.md#destructors)
+> -   [Classes: Destructors](classes.md#destructors)
 > -   Proposal
 >     [#1154: Destructors](https://github.com/carbon-language/carbon-lang/pull/1154)
 
 #### `const`
 
-**Note:** This is provisional, no design for `const` has been through the
-proposal process yet.
+> **Note:** This is provisional, no design for `const` has been through the
+> proposal process yet.
 
 For every type `MyClass`, there is the type `const MyClass` such that:
 
@@ -1672,6 +1728,12 @@ when returning a value from a function or by using the _move operator_ `~x`.
 This leaves `x` in an [unformed state](#unformed-state) and returns its old
 value.
 
+> **Note:** This is provisional. The move operator was discussed but not
+> proposed in accepted proposal
+> [#257: Initialization of memory and variables](https://github.com/carbon-language/carbon-lang/pull/257).
+> See pending proposal
+> [#821: Values, variables, pointers, and references](https://github.com/carbon-language/carbon-lang/pull/821).
+
 #### Mixins
 
 Mixins allow reuse with different trade-offs compared to
@@ -1681,7 +1743,9 @@ be done using
 [multiple inheritance](https://en.wikipedia.org/wiki/Multiple_inheritance) in
 C++.
 
-**TODO:** The design for mixins is still under development.
+> **TODO:** The design for mixins is still under development. The details here
+> are provisional. The mixin use case was included in accepted proposal
+> [#561: Basic classes: use cases, struct literals, struct types, and future work](https://github.com/carbon-language/carbon-lang/pull/561).
 
 ### Choice types
 
@@ -1921,7 +1985,7 @@ given name public.
 
 ### Package scope
 
-The top-level scope in a package is the scope of the package. This means:
+The top-level scope in a file is the scope of the package. This means:
 
 -   Within this scope (and its sub-namespaces), all visible names from the same
     package appear. This includes names from the same file, names from the `api`
@@ -2036,6 +2100,12 @@ P.M.Q();
 >
 > -   ["Namespaces" in "Code and name organization"](code_and_name_organization/README.md#namespaces)
 > -   ["Package and namespace members" in "Qualified names and member access"](expressions/member_access.md#package-and-namespace-members)
+> -   Proposal
+>     [#107: Code and name organization](https://github.com/carbon-language/carbon-lang/pull/107)
+> -   Proposal
+>     [#989: Member access expressions](https://github.com/carbon-language/carbon-lang/pull/989)
+> -   Question-for-leads issue
+>     [#1136: what is the top-level scope in a source file, and what names are found there?](https://github.com/carbon-language/carbon-lang/issues/1136)
 
 ### Naming conventions
 
@@ -2106,9 +2176,13 @@ class ContactInfo {
 > -   [`alias` a name from an external impl](generics/details.md#external-impl)
 > -   [`alias` a name in a named constraint](generics/details.md#named-constraints)
 > -   Proposal
+>     [#107: Code and name organization](https://github.com/carbon-language/carbon-lang/pull/107)
+> -   Proposal
 >     [#553: Generics details part 1](https://github.com/carbon-language/carbon-lang/pull/553)
 > -   Question-for-leads issue
 >     [#749: Alias syntax](https://github.com/carbon-language/carbon-lang/issues/749)
+> -   Proposal
+>     [#989: Member access expressions](https://github.com/carbon-language/carbon-lang/pull/989)
 
 ### Name lookup
 
@@ -2593,6 +2667,10 @@ indicate that they may not be specialized, subject to
 >     [#920: Generic parameterized impls (details 5)](https://github.com/carbon-language/carbon-lang/pull/920)
 > -   Proposal
 >     [#983: Generics details 7: final impls](https://github.com/carbon-language/carbon-lang/pull/983)
+> -   Question-for-leads issue
+>     [1192: Parameterized impl syntax](https://github.com/carbon-language/carbon-lang/issues/1192)
+> -   Proposal
+>     [#1327: Generics: `impl forall`](https://github.com/carbon-language/carbon-lang/pull/1327)
 
 ### Other features
 
@@ -2620,9 +2698,9 @@ Carbon generics have a number of other features, including:
     value with a type implementing an interface, and allows the functions in
     that interface to be called using
     [dynamic dispatch](https://en.wikipedia.org/wiki/Dynamic_dispatch), for some
-    interfaces marked "`dyn`-safe".
+    interfaces marked "`dyn`-safe". **Note:** Provisional.
 -   [Variadics](generics/details.md#variadic-arguments) supports variable-length
-    parameter lists.
+    parameter lists. **Note:** Provisional.
 
 > References:
 >
@@ -2883,6 +2961,9 @@ include:
 
 ### Importing and `#include`
 
+> **Note:** This is provisional, no design for importing C++ has been through
+> the proposal process yet.
+
 A C++ library header file may be [imported](#imports) into Carbon using an
 `import` declaration of the special `Cpp` package.
 
@@ -2919,6 +3000,9 @@ marker.
 
 ### ABI and dynamic linking
 
+> **Note:** This reflects goals and plans. No specific design for the
+> implementation has been through the proposal process yet.
+
 Carbon itself will not have a stable ABI for the language as a whole, and most
 language features will be designed around not having any ABI stability. Instead,
 we expect to add dedicated language features that are specifically designed to
@@ -2943,8 +3027,16 @@ available across this interop boundary will of course be restricted to what is
 expressible in the C ABI, and types may need explicit markers to have guaranteed
 ABI compatibility.
 
+> References:
+>
+> -   [Goals: Stable language and library ABI non-goal](https://github.com/carbon-language/carbon-lang/blob/trunk/docs/project/goals.md#stable-language-and-library-abi)
+> -   [#175: C++ interoperability goals: Support mixing Carbon and C++ toolchains](/proposals/p0175.md#support-mixing-carbon-and-c-toolchains)
+
 ### Operator overloading
 
+> **Note:** This is provisional, no design for this has been through the
+> proposal process yet.
+
 [Operator overloading](#operator-overloading) is supported in Carbon, but is
 done by [implementing an interface](#interfaces-and-implementations) instead of
 defining a method or nonmember function as in C++.
@@ -2984,6 +3076,9 @@ requiring changes to importers?
 
 ### Templates
 
+> **Note:** This is provisional, no design for this has been through the
+> proposal process yet.
+
 Carbon supports both
 [checked and template generics](#checked-and-template-parameters). This provides
 a migration path for C++ template code:
@@ -3012,6 +3107,9 @@ if it were a C++ template.
 
 ### Standard types
 
+> **Note:** This is provisional, no design for this has been through the
+> proposal process yet.
+
 The Carbon integer types, like `i32` and `u64`, are considered equal to the
 corresponding fixed-width integer types in C++, like `int32_t` and `uint64_t`,
 provided by `<stdint.h>` or `<cstdint>`. The basic C and C++ integer types like
@@ -3076,12 +3174,21 @@ The reverse operation is also possible using a proxy object implementing a C++
 abstract base class and holding a pointer to a type implementing the
 corresponding interface.
 
+> References:
+>
+> -   Proposal
+>     [#561: Basic classes: use cases, struct literals, struct types, and future work](https://github.com/carbon-language/carbon-lang/pull/561)
+> -   Proposal
+>     [#777: Inheritance](https://github.com/carbon-language/carbon-lang/pull/777)
+
 ### Enums
 
 > **TODO**
 
 ## Unfinished tales
 
+> **Note:** Everything in this section is provisional and forward looking.
+
 ### Safety
 
 Carbon's premise is that C++ users can't give up performance to get safety. Even