Transcribe the rest of I.8.6.1.X signatures

docs/i.11-collected-common-language-specification-rules.md

@@ -26,11 +26,11 @@ The complete set of CLS rules are collected here for reference. Recall that thes
 
 **CLS Rule 12:** The visibility and accessibility of types and members shall be such that types in the signature of any member shall be visible and accessible whenever the member itself is visible and accessible. For example, a public method that is visible outside its assembly shall not have an argument whose type is visible only within the assembly. The visibility and accessibility of types composing an instantiated generic type used in the signature of any member shall be visible and accessible whenever the member itself is visible and accessible. For example, an instantiated generic type present in the signature of a member that is visible outside its assembly shall not have a generic argument whose type is visible only within the assembly. (§[I.8.6.1](i.8.6.1-signatures.md))
 
-**CLS Rule 13:** The value of a literal static is specified through the use of field initialization metadata (see Partition II Metadata). A CLS-compliant literal must have a value specified in field initialization metadata that is of exactly the same type as the literal (or of the underlying type, if that literal is an enum). (§[I.8.6.1.2](#todo-missing-hyperlink))
+**CLS Rule 13:** The value of a literal static is specified through the use of field initialization metadata (see Partition II Metadata). A CLS-compliant literal must have a value specified in field initialization metadata that is of exactly the same type as the literal (or of the underlying type, if that literal is an enum). (§[I.8.6.1.2](i.8.6.1.2-location-signatures.md))
 
-**CLS Rule 14:** Typed references are not CLS-compliant. (§[I.8.6.1.3](#todo-missing-hyperlink))
+**CLS Rule 14:** Typed references are not CLS-compliant. (§[I.8.6.1.3](i.8.6.1.3-local-signatures.md))
 
-**CLS Rule 15:** The vararg constraint is not part of the CLS, and the only calling convention supported by the CLS is the standard managed calling convention. (§[I.8.6.1.5](#todo-missing-hyperlink))
+**CLS Rule 15:** The vararg constraint is not part of the CLS, and the only calling convention supported by the CLS is the standard managed calling convention. (§[I.8.6.1.5](i.8.6.1.5-method-signatures.md))
 
 **CLS Rule 16:** Arrays shall have elements with a CLS-compliant type, and all dimensions of the array shall have lower bounds of zero. Only the fact that an item is an array and the element type of the array shall be required to distinguish between overloads.  When overloading is based on two or more array types the element types shall be named types. (§[I.8.9.1](i.8.9.1-array-types.md))
 

docs/i.8.2.1.1-managed-pointers-and-related-types.md

@@ -1,9 +1,9 @@
 ## I.8.2.1.1 Managed pointers and related types
 
-A **managed pointer** (§[I.12.1.1.2](i.12.1.1.2-object-reference-and-managed-pointer-types-o-and-ref.md)), or **byref** (§[I.8.6.1.3](#todo-missing-hyperlink), §[I.12.4.1.5.2](i.12.4.1.5.2-by-reference-parameters.md)), can point to a local variable, parameter, field of a compound type, or element of an array. However, when a call crosses a remoting boundary (see §[I.12.5](i.12.5-proxies-and-remoting.md)) a conforming implementation can use a copy-in/copyout mechanism instead of a managed pointer. Thus programs shall not rely on the aliasing behavior of true pointers. Managed pointer types are only allowed for  local variable (§[I.8.6.1.3](#todo-missing-hyperlink)) and parameter signatures (§[I.8.6.1.4](#todo-missing-hyperlink)); they cannot be used for field signatures (§[I.8.6.1.2](#todo-missing-hyperlink)), as the element type of an array (§[I.8.9.1](i.8.9.1-array-types.md)), and boxing a value of managed pointer type is disallowed (§[I.8.2.4](i.8.2.4-boxing-and-unboxing-of-values.md)). Using a managed pointer type for the return type of methods (§[I.8.6.1.5](#todo-missing-hyperlink)) is not verifiable (§[I.8.8](i.8.8-type-safety-and-verification.md)).
+A **managed pointer** (§[I.12.1.1.2](i.12.1.1.2-object-reference-and-managed-pointer-types-o-and-ref.md)), or **byref** (§[I.8.6.1.3](i.8.6.1.3-local-signatures.md), §[I.12.4.1.5.2](i.12.4.1.5.2-by-reference-parameters.md)), can point to a local variable, parameter, field of a compound type, or element of an array. However, when a call crosses a remoting boundary (see §[I.12.5](i.12.5-proxies-and-remoting.md)) a conforming implementation can use a copy-in/copyout mechanism instead of a managed pointer. Thus programs shall not rely on the aliasing behavior of true pointers. Managed pointer types are only allowed for  local variable (§[I.8.6.1.3](i.8.6.1.3-local-signatures.md)) and parameter signatures (§[I.8.6.1.4](i.8.6.1.4-paramater-signatures.md)); they cannot be used for field signatures (§[I.8.6.1.2](i.8.6.1.2-location-signatures.md)), as the element type of an array (§[I.8.9.1](i.8.9.1-array-types.md)), and boxing a value of managed pointer type is disallowed (§[I.8.2.4](i.8.2.4-boxing-and-unboxing-of-values.md)). Using a managed pointer type for the return type of methods (§[I.8.6.1.5](i.8.6.1.5-method-signatures.md)) is not verifiable (§[I.8.8](i.8.8-type-safety-and-verification.md)).
 
 _[Rationale:_ For performance reasons items on the GC heap may not contain references to the interior of other GC objects, this motivates the restrictions on fields and boxing. Further returning a managed pointer which references a local or parameter variable may cause the reference to outlive the variable, hence it is not verifiable. _end rationale]_
 
 There are three value types in the Base Class Library (see [Partition IV - BCL](#todo-missing-hyperlink)): `System.TypedReference`, `System.RuntimeArgumentHandle`, and `System.ArgIterator`; which are treated specially by the CLI.
 
-The value type `System.TypedReference`, or **typed reference** or **typedref**, (§[I.8.2.2](i.8.2.2-built-in-value-and-reference-types.md), §[I.8.6.1.3](#todo-missing-hyperlink), §[I.12.4.1.5.3]) contains both a managed pointer to a location and a runtime representation of the type that can be stored at that location. Typed references have the same restrictions as byrefs. Typed references are created by the CIL instruction mkrefany (see [Partition III](#todo-missing-hyperlink)). The value types `System.RuntimeArgumentHandle` and `System.ArgIterator` (see [Partition IV](#todo-missing-hyperlink) and CIL instruction `arglist` in [Partition III](#todo-missing-hyperlink)), contain pointers into the VES stack. They can be used for local variable and parameter signatures. The use of these types for fields, method return types, the element type of an array, or in boxing is not verifiable (§[I.8.8](i.8.8-type-safety-and-verification.md)). These two types are referred to as **byref-like** types.
+The value type `System.TypedReference`, or **typed reference** or **typedref**, (§[I.8.2.2](i.8.2.2-built-in-value-and-reference-types.md), §[I.8.6.1.3](i.8.6.1.3-local-signatures.md), §[I.12.4.1.5.3]) contains both a managed pointer to a location and a runtime representation of the type that can be stored at that location. Typed references have the same restrictions as byrefs. Typed references are created by the CIL instruction mkrefany (see [Partition III](#todo-missing-hyperlink)). The value types `System.RuntimeArgumentHandle` and `System.ArgIterator` (see [Partition IV](#todo-missing-hyperlink) and CIL instruction `arglist` in [Partition III](#todo-missing-hyperlink)), contain pointers into the VES stack. They can be used for local variable and parameter signatures. The use of these types for fields, method return types, the element type of an array, or in boxing is not verifiable (§[I.8.8](i.8.8-type-safety-and-verification.md)). These two types are referred to as **byref-like** types.

docs/i.8.5.2-assemblies-and-scoping.md

@@ -40,7 +40,7 @@ The CTS supports an **enum** (also known as an **enumeration type**), an alterna
 
  * It shall not have any properties or events of its own. 
 
- * It shall not have any static fields unless they are literal. (see §[I.8.6.1.2](#todo-missing-hyperlink))
+ * It shall not have any static fields unless they are literal. (see §[I.8.6.1.2](i.8.6.1.2-location-signatures.md))
 
 The underlying type shall be a built-in integer type. Enums shall derive from `System.Enum`, hence they are value types. Like all value types, they shall be sealed (see §[I.8.9.9](i.8.9.9-object-type-inheritance.md)).
 

docs/i.8.6.1-signatures.md

@@ -1,6 +1,6 @@
 ## I.8.6.1 Signatures
 
-**Signatures** are the part of a contract that can be checked and automatically enforced. Signatures are formed by adding constraints to types and other signatures. A constraint is a limitation on the use of or allowed operations on a value or location. Example constraints would be whether a location can be overwritten with a different value or whether a value can ever be changed. All locations have signatures, as do all values. Assignment compatibility requires that the signature of the value, including constraints, be compatible with the signature of the location, including constraints. There are four fundamental kinds of signatures: type signatures (see §[I.8.6.1.1](i.8.6.1.1-type-signatures.md)), location signatures (see §[I.8.6.1.2](#todo-missing-hyperlink)), parameter signatures (see §[I.8.6.1.4](#todo-missing-hyperlink)), and method signatures (see §[I.8.6.1.5](#todo-missing-hyperlink)). (A fifth kind, a local signature (see §[I.8.6.1.3](#todo-missing-hyperlink)) is really a version of a location signature.)
+**Signatures** are the part of a contract that can be checked and automatically enforced. Signatures are formed by adding constraints to types and other signatures. A constraint is a limitation on the use of or allowed operations on a value or location. Example constraints would be whether a location can be overwritten with a different value or whether a value can ever be changed. All locations have signatures, as do all values. Assignment compatibility requires that the signature of the value, including constraints, be compatible with the signature of the location, including constraints. There are four fundamental kinds of signatures: type signatures (see §[I.8.6.1.1](i.8.6.1.1-type-signatures.md)), location signatures (see §[I.8.6.1.2](i.8.6.1.2-location-signatures.md)), parameter signatures (see §[I.8.6.1.4](i.8.6.1.4-paramater-signatures.md)), and method signatures (see §[I.8.6.1.5](i.8.6.1.5-method-signatures.md)). (A fifth kind, a local signature (see §[I.8.6.1.3](i.8.6.1.3-local-signatures.md)) is really a version of a location signature.)
 
 > #### CLS Rule 11:
 >

docs/i.8.6.1.2-location-signatures.md

@@ -0,0 +1,21 @@
+## I.8.6.1.2 Location signatures
+
+All locations are typed. This means that all locations have a **location signature**, which defines constraints on the location, its usage, and on the usage of the values stored in the location. Any valid type signature is a valid location signature. Hence, a location signature contains a type and can additionally contain the constant constraint. The location signature can also contain **location constraints** that give further restrictions on the uses of the location. The location constraints are:
+
+ * The **init-only constraint** promises (hence, requires) that once the location has been initialized, its contents never change. Namely, the contents are initialized before any access, and after initialization, no value can be stored in the location. The contents are always identical to the initialized value (see §[I.8.2.3](i.8.2.3-classes-interfaces-and-objects.md)). This constraint, while logically applicable to any location, shall only be placed on fields (static or instance) of compound types.
+
+ * The **literal constraint** promises that the value of the location is actually a fixed value of a built-in type. The value is specified as part of the constraint. Compilers are required to replace all references to the location with its value, and the VES therefore need not allocate space for the location. This constraint, while logically applicable to any location, shall only be placed on static fields of compound types. Fields that are so marked are not permitted to be referenced from CIL (they shall be in-lined to their constant value at compile time), but are available using reflection and tools that directly deal with the metadata.
+
+> #### CLS Rule 13:
+>
+> The value of a literal static is specified through the use of field initialization metadata (see [Partition II Metadata](ii.5.9-attributes-and-metadata.md)). A CLS-compliant literal must have a value specified in field initialization metadata that is of exactly the same type as the literal (or of the underlying type, if that literal is an **enum**).
+>
+> _[Note:_
+>
+> **CLS (consumer):** Must be able to read field initialization metadata for static literal fields and inline the value specified when referenced. Consumers can assume that the type of the field initialization metadata is exactly the same as the type of the literal field (i.e., a consumer tool need not implement conversions of the values).
+>
+> **CLS (extender):** Must avoid producing field initialization metadata for static literal fields in which the type of the field initialization metadata does not exactly match the type of the field.
+>
+> **CLS (framework):** Should avoid the use of syntax specifying a value of a literal that requires conversion of the value. Note that compilers can do the conversion themselves before persisting the field initialization metadata resulting in a CLS-compliant framework, but frameworks are encouraged not to rely on such implicit conversions _end note]_
+
+_[Note:_ It might seem reasonable to provide a volatile constraint on a location that would require that the value stored in the location not be cached between accesses. Instead, CIL includes a `volatile.` prefix to certain instructions to specify that the value neither be cached nor computed using an existing cache. Such a constraint can be encoded using a custom attribute (see §[I.9.7](i.9.7-metadata-extensibility.md)), although this standard does not specify such an attribute. _end note]_

docs/i.8.6.1.3-local-signatures.md

@@ -0,0 +1,21 @@
+## I.8.6.1.3 Local signatures
+
+A **local signature** specifies the contract on a local variable allocated during the running of a method. A local signature contains a full location signature, plus it can specify one additional constraint:
+
+The **byref** constraint states that the content of the corresponding location is a **managed pointer**. A managed pointer can point to a local variable, parameter, field of a compound type, or element of an array. However, when a call crosses a remoting boundary (see §[I.12.5](i.12.5-proxies-and-remoting.md)) a conforming implementation can use a copy-in/copy-out mechanism instead of a managed pointer. Thus programs shall not rely on the aliasing behavior of true pointers.
+
+In addition, there is one special local signature. The **typed reference** local variable signature states that the local will contain both a managed pointer to a location and a runtime representation of the type that can be stored at that location. A typed reference signature is similar to a byref constraint, but while the byref specifies the type as part of the byref constraint (and hence statically as part of the type description), a typed reference provides the type information dynamically. A typed reference is a full signature in itself and cannot be combined with other constraints. In particular, it is not possible to specify a **byref** whose type is **typed reference**.
+
+The typed reference signature is actually represented as a built-in value type, like the integer and floating-point types. In the Base Class Library (see [Partition IV Library](iv.5.3-base-class-library-bcl.md)) the type is known as `System.TypedReference` and in the assembly language used in [Partition II](ii.22-metadata-logical-format-tables.md) it is designated by the keyword **typedref**. This type shall only be used for parameters and local variables. It shall not be boxed, nor shall it be used as the type of a field, element of an array, or return value.
+
+> #### CLS Rule 14:
+>
+> Typed references are not CLS-compliant.
+>
+> _[Note:_
+>
+> **CLS (consumer):** There is no need to accept this type.
+>
+> **CLS (extender):** There is no need to provide syntax to define this type or to extend interfaces or classes that use this type.
+>
+> **CLS (framework):** This type shall not appear in exported members. _end note]_

docs/i.8.6.1.4-paramater-signatures.md

@@ -0,0 +1,3 @@
+## I.8.6.1.4 Parameter signatures
+
+A **parameter signature**, defines constraints on how an individual value is passed as part of a method invocation. Parameter signatures are declared by method definitions. Any valid local signature is a valid parameter signature.

docs/i.8.6.1.5-method-signatures.md

@@ -0,0 +1,41 @@
+## I.8.6.1.5 Method signatures
+
+A **method signature** is composed of
+
+ * a calling convention,
+ * the number of generic parameters, if the method is generic,
+ * if the calling convention specifies this is an instance method and the owning method definition belongs to a type T then the type of the `this` pointer is:
+     * given by the first parameter signature, if the calling convention is `instance explicit` (§[II.15.3](ii.15.3-calling-convention.md)),
+     * inferred as &T, if T is a value type and the method definition is non-virtual (§[I.8.9.7](i.8.9.7-value-type-definition.md)),
+     * inferred as "boxed" T, if T is a value type and the method definition is virtual (this includes method definitions from an interface implemented by T) (§[I.8.9.7](i.8.9.7-value-type-definition.md)),
+     * inferred as T, otherwise
+ * a list of zero or more parameter signatures—one for each parameter of the method— and,
+ * a type signature for the result value, if one is produced.
+
+Method signatures are declared by method definitions. Only one constraint can be added to a method signature in addition to those of parameter signatures:
+
+ * The **vararg** constraint can be included to indicate that all arguments past this point are optional. When it appears, the calling convention shall be one that supports variable argument lists.
+
+Method signatures are used in two different ways: as part of a method definition and as a description of a calling site when calling through a function pointer. In the latter case, the method signature indicates
+
+ * the calling convention (which can include platform-specific calling conventions),
+ * the types of all the argument values that are being passed, and
+ * if needed, a vararg marker indicating where the fixed parameter list ends and the variable parameter list begins.
+
+When used as part of a method definition, the vararg constraint is represented by the choice of calling convention. 
+
+_[Note:_ a single _method implementation_ may be used both to satisfy a _method definition_ of a type and to satisfy a _method definition_ of an interface the type implements. If the type is a value type, T, then the `this` pointer in the method signature for the type's own _method definition_ is a managed pointer &T, while it is "boxed" T in the method signature associated with the interface's _method definition._ _end note]_
+
+_[Note:_ the presence of a `this` pointer affects parameter signature/argument number pairing in CIL. If the parameter signature for the `this` pointer is inferred then the first parameter signature in the metadata is for argument number one. If there is no `this` pointer, as with static methods, or this is an `instance explicit` method, then the first parameter signature is for argument number zero. See the descriptions of the call and load function instructions in Partition III. _end note]_
+
+> #### CLS Rule 15:
+>
+> The vararg constraint is not part of the CLS, and the only calling convention supported by the CLS is the standard managed calling convention.
+>
+> _[Note:_
+>
+> **CLS (consumer):** There is no need to accept methods with variable argument lists or unmanaged calling convention.
+>
+> **CLS (extender):** There is no need to provide syntax to declare vararg methods or unmanaged calling conventions.
+>
+> **CLS (framework):** Neither vararg methods nor methods with unmanaged calling conventions shall be exported externally. _end note]_