Updates to design docs to reflect accepted proposals (#3254)

Includes proposals:
- #990
- #2188
- #2138
- #2200
- #2360
- #2760
- #2964
- #3162

Also tries to use more precise language when talking about:
- implementations, to avoid confusing `impl` declaration and definitions
with the `impls` operator used in `where` clauses, an issue brought up
in #2495 and #2483;
- "binding patterns", like `x: i32`, and "bindings" like `x`.

---------

Co-authored-by: Chandler Carruth <[email protected]>

Author: josh11b

docs/design/README.md

@@ -1604,14 +1604,13 @@ 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)
 > -   Question-for-leads issue
 >     [#1283: how should pattern matching and implicit conversion interact?](https://github.com/carbon-language/carbon-lang/issues/1283)
+> -   Proposal
+>     [#2188: Pattern matching syntax and semantics](https://github.com/carbon-language/carbon-lang/pull/2188)
 
 ## User-defined types
 
@@ -3562,9 +3561,6 @@ imported, so a wrapper may be added without 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:
@@ -3591,6 +3587,11 @@ toolchain. However, even when using Carbon's generated C++ headers for interop,
 we will include the ability where possible to use a Carbon generic from C++ as
 if it were a C++ template.
 
+> References:
+>
+> -   Proposal
+>     [#2200: Template generics](https://github.com/carbon-language/carbon-lang/pull/2200)
+
 ### Standard types
 
 > **Note:** This is provisional, no design for this has been through the

docs/design/classes.md

@@ -311,8 +311,8 @@ implemented in descendants.
 While it is typical for this case to be associated with single-level inheritance
 hierarchies, there are some cases where there is an interface at the root of a
 type hierarchy and polymorphic types as interior branches of the tree. The case
-of generic interfaces extending or requiring other interface would also be
-modeled by deeper inheritance hierarchies.
+of interfaces extending or requiring other interface would also be modeled by
+deeper inheritance hierarchies.
 
 An interface as base class needs to either have a virtual destructor or forbid
 deallocation.
@@ -325,7 +325,7 @@ that support dynamic dispatch are called _object-safe_, following
 
 -   They don't have a `Self` in the signature of a method in a contravariant
     position like a parameter.
--   They don't have free associated types or other associated items used in a
+-   They don't have free associated facets or other associated items used in a
     method signature.
 
 The restrictions on object-safe interfaces match the restrictions on base class
@@ -910,7 +910,7 @@ which must be an
 then match pattern '`self:` _type_' against it".
 
 If the method declaration also includes
-[deduced generic parameters](/docs/design/generics/overview.md#deduced-parameters),
+[deduced compile-time parameters](/docs/design/generics/overview.md#deduced-parameters),
 the `self` parameter must be in the same list in square brackets `[`...`]`. The
 `self` parameter may appear in any position in that list, as long as it appears
 after any names needed to describe its type.
@@ -1595,7 +1595,7 @@ class MyDerivedClass {
 
 The properties of a type, whether type is abstract, base, or final, and whether
 the destructor is virtual or non-virtual, determines which
-[type-of-types](/docs/design/generics/terminology.md#facet-type) it satisfies.
+[facet types](/docs/design/generics/terminology.md#facet-type) it satisfies.
 
 -   Non-abstract classes are `Concrete`. This means you can create local and
     member variables of this type. `Concrete` types have destructors that are
@@ -1623,9 +1623,9 @@ conform to the decision on
 | final    | any         | yes        | yes         | yes            |
 
 The compiler automatically determines which of these
-[type-of-types](/docs/design/generics/terminology.md#facet-type) a given type
+[facet types](/docs/design/generics/terminology.md#facet-type) a given type
 satisfies. It is illegal to directly implement `Concrete`, `Deletable`, or
-`Destructible` directly. For more about these constraints, see
+`Destructible`. For more about these constraints, see
 ["destructor constraints" in the detailed generics design](/docs/design/generics/details.md#destructor-constraints).
 
 A pointer to `Deletable` types may be passed to the `Delete` method of the
@@ -1644,8 +1644,9 @@ interface Allocator {
 }
 ```
 
-To pass a pointer to a base class without a virtual destructor to a generic
-function expecting a `Deletable` type, use the `UnsafeAllowDelete`
+To pass a pointer to a base class without a virtual destructor to a
+checked-generic function expecting a `Deletable` type, use the
+`UnsafeAllowDelete`
 [type adapter](/docs/design/generics/details.md#adapting-types).
 
 ```
@@ -1670,7 +1671,7 @@ and not implemented in the current class.
 
 Types satisfy the
 [`TrivialDestructor`](/docs/design/generics/details.md#destructor-constraints)
-type-of-type if:
+facet type if:
 
 -   the class declaration does not define a destructor or the class defines the
     destructor with an empty body `{ }`,
@@ -1949,11 +1950,11 @@ We want four things so that Carbon's object-safe interfaces may interoperate
 with C++ abstract base classes without data members, matching the
 [interface as base class use case](#interface-as-base-class):
 
--   Ability to convert an object-safe interface (a type-of-type) into an
+-   Ability to convert an object-safe interface (a facet type) into an
     C++-compatible base class (a base type), maybe using
     `AsBaseClass(MyInterface)`.
 -   Ability to convert a C++ base class without data members (a base type) into
-    an object-safe interface (a type-of-type), maybe using `AsInterface(MyIBC)`.
+    an object-safe interface (a facet type), maybe using `AsInterface(MyIBC)`.
 -   Ability to convert a (thin) pointer to an abstract base class to a `DynPtr`
     of the corresponding interface.
 -   Ability to convert `DynPtr(MyInterface)` values to a proxy type that extends
@@ -2160,7 +2161,7 @@ implementations for [data classes](#data-classes) more generally. These
 implementations will typically subject to the criteria that all the data fields
 of the type must implement the interface. An example use case would be to say
 that a data class is serializable if all of its fields were. For this we will
-need a type-of-type for capturing that criteria, maybe something like
+need a facet type for capturing that criteria, maybe something like
 `DataFieldsImplement(MyInterface)`. The templated implementation will need some
 way of iterating through the fields so it can perform operations fieldwise. This
 feature should also implement the interfaces for any tuples whose fields satisfy
@@ -2239,7 +2240,7 @@ the type of `U.x`."
     -   [Allow functions to act as destructors](/proposals/p1154.md#allow-functions-to-act-as-destructors)
     -   [Allow private destructors](/proposals/p1154.md#allow-private-destructors)
     -   [Allow multiple conditional destructors](/proposals/p1154.md#allow-multiple-conditional-destructors)
-    -   [Type-of-type naming](/proposals/p1154.md#type-of-type-naming)
+    -   [Facet type naming](/proposals/p1154.md#type-of-type-naming)
     -   [Other approaches to extensible classes without vtables](/proposals/p1154.md#other-approaches-to-extensible-classes-without-vtables)
 
 -   [#2107: Clarify rules around `Self` and `.Self`](https://github.com/carbon-language/carbon-lang/pull/2107)

docs/design/expressions/arithmetic.md

@@ -193,15 +193,15 @@ following family of interfaces:
 ```
 // Unary `-`.
 interface Negate {
-  let Result:! type = Self;
+  default let Result:! type = Self;
   fn Op[self: Self]() -> Result;
 }
 ```
 
 ```
 // Binary `+`.
 interface AddWith(U:! type) {
-  let Result:! type = Self;
+  default let Result:! type = Self;
   fn Op[self: Self](other: U) -> Result;
 }
 constraint Add {
@@ -212,7 +212,7 @@ constraint Add {
 ```
 // Binary `-`.
 interface SubWith(U:! type) {
-  let Result:! type = Self;
+  default let Result:! type = Self;
   fn Op[self: Self](other: U) -> Result;
 }
 constraint Sub {
@@ -223,7 +223,7 @@ constraint Sub {
 ```
 // Binary `*`.
 interface MulWith(U:! type) {
-  let Result:! type = Self;
+  default let Result:! type = Self;
   fn Op[self: Self](other: U) -> Result;
 }
 constraint Mul {
@@ -234,7 +234,7 @@ constraint Mul {
 ```
 // Binary `/`.
 interface DivWith(U:! type) {
-  let Result:! type = Self;
+  default let Result:! type = Self;
   fn Op[self: Self](other: U) -> Result;
 }
 constraint Div {
@@ -245,7 +245,7 @@ constraint Div {
 ```
 // Binary `%`.
 interface ModWith(U:! type) {
-  let Result:! type = Self;
+  default let Result:! type = Self;
   fn Op[self: Self](other: U) -> Result;
 }
 constraint Mod {

docs/design/expressions/bitwise.md

@@ -197,15 +197,15 @@ implementing the following family of interfaces:
 ```
 // Unary `^`.
 interface BitComplement {
-  let Result:! type = Self;
+  default let Result:! type = Self;
   fn Op[self: Self]() -> Result;
 }
 ```
 
 ```
 // Binary `&`.
 interface BitAndWith(U:! type) {
-  let Result:! type = Self;
+  default let Result:! type = Self;
   fn Op[self: Self](other: U) -> Result;
 }
 constraint BitAnd {
@@ -216,7 +216,7 @@ constraint BitAnd {
 ```
 // Binary `|`.
 interface BitOrWith(U:! type) {
-  let Result:! type = Self;
+  default let Result:! type = Self;
   fn Op[self: Self](other: U) -> Result;
 }
 constraint BitOr {
@@ -227,7 +227,7 @@ constraint BitOr {
 ```
 // Binary `^`.
 interface BitXorWith(U:! type) {
-  let Result:! type = Self;
+  default let Result:! type = Self;
   fn Op[self: Self](other: U) -> Result;
 }
 constraint BitXor {
@@ -238,7 +238,7 @@ constraint BitXor {
 ```
 // Binary `<<`.
 interface LeftShiftWith(U:! type) {
-  let Result:! type = Self;
+  default let Result:! type = Self;
   fn Op[self: Self](other: U) -> Result;
 }
 constraint LeftShift {
@@ -249,7 +249,7 @@ constraint LeftShift {
 ```
 // Binary `>>`.
 interface RightShiftWith(U:! type) {
-  let Result:! type = Self;
+  default let Result:! type = Self;
   fn Op[self: Self](other: U) -> Result;
 }
 constraint RightShift {

docs/design/expressions/comparison_operators.md

@@ -241,8 +241,8 @@ User-defined types can extend the behavior of the comparison operators by
 implementing interfaces. In this section, various properties are specified that
 such implementations "should" satisfy. These properties are not enforced in
 general, but the standard library might detect violations of some of them in
-some circumstances. These properties may be assumed by generic code, resulting
-in unexpected behavior if they are violated.
+some circumstances. These properties may be assumed by checked-generic code,
+resulting in unexpected behavior if they are violated.
 
 #### Equality
 
@@ -460,7 +460,7 @@ than or equivalent to themselves.
 
 **TODO:** The standard library should provide a way to specify that an ordering
 is a weak, partial, or total ordering, and a way to request such an ordering in
-a generic.
+a checked generic.
 
 #### Compatibility of equality and ordering
 

docs/design/expressions/if.md

@@ -175,8 +175,8 @@ _Note:_ This rule is intended to be considered more specialized than the other
 rules in this document.
 
 Because this `impl` is declared `final`, `T.(CommonType(T)).Result` is always
-assumed to be `T`, even in contexts where `T` involves a generic parameter and
-so the result would normally be an unknown type whose type-of-type is `type`.
+assumed to be `T`, even in contexts where `T` involves a symbolic binding and so
+the result would normally be an unknown type whose facet type is `type`.
 
 ```
 fn F[T:! Hashable](c: bool, x: T, y: T) -> HashCode {

docs/design/expressions/indexing.md

@@ -51,7 +51,7 @@ pointer, and do not automatically chain with customized dereference interfaces.
 
 **Open question:** It's not clear that the lack of chaining is necessary, and it
 might be more expressive for the pointer type returned by the `Addr` methods to
-be an associated type with a default to allow types to produce custom
+be an associated facet with a default to allow types to produce custom
 pointer-like types on their indexing boundary and have them still be
 automatically dereferenced.
 

docs/design/functions.md

@@ -151,14 +151,14 @@ the `a` and `b` parameters of `Add`.
 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.
+    deduced parameters and compile-time parameters.
 -   [Class member functions](classes.md#member-functions) adds support for
     methods and class functions.
 
 ## 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)
+-   [Only allow `auto` return types if parameters are compile-time](/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)
 

docs/design/generics/README.md

@@ -11,11 +11,14 @@ feature of Carbon:
 
 -   [Overview](overview.md) - A high-level description of the generics design,
     with pointers to other design documents that dive deeper into individual
-    topics.
+    topics
 -   [Goals](goals.md) - The motivation and principles guiding the design
-    direction.
+    direction
 -   [Terminology](terminology.md) - A glossary establishing common terminology
-    for describing the design.
--   [Detailed design](details.md) - In depth description of how generic type
-    parameters work.
--   ~~Rejected alternatives~~ - not implemented yet
+    for describing the design
+-   [Detailed design](details.md) - In-depth description
+    -   [Appendix: Witness tables](appendix-witness.md) - Describes an
+        implementation strategy for checked generics, and Carbon's rationale for
+        only using it for dynamic dispatch.
+    -   [Appendix: Coherence](appendix-coherence.md) - Describes the rationale
+        for Carbon's choice to have coherent generics, and the alternatives.

docs/design/generics/appendix-witness.md

@@ -213,8 +213,8 @@ class Vector {
 }
 ```
 
-The [impl of `Vector` for `Point_Inline`](details.md#inline-impl) would be a
-value of this type:
+The [`impl` definition of `Vector` for `Point_Inline`](details.md#inline-impl)
+would be a value of this type:
 
 ```
 var VectorForPoint_Inline: Vector  = {