Port text from dotnet#700

The first commit ports in the text from dotnet#700 substantially without change. The only editorial change is to move the clause on "Nullable directives" in lexical-structure before the clause on Pragma directives.

fix build warnings

This will likely cause new failures, as I turned on nullable annotations and warnings in one of the templates.

Update code samples for the template in use to remove nullable warnings.

I did this as we plan to have nullable annotations on by default in this version of the spec.

Revert "fix build warnings"

This reverts commit dcb3731.

test for nullable annotations

If the samples compile cleanly in this mode, I can continue in this PR without breaking all the samples.

revert changes for type system.

Author: BillWagner

standard/attributes.md

@@ -490,7 +490,7 @@ The attribute instance represented by `T`, `C`, `P`, and `N`, and associated wi
 <!-- markdownlint-enable MD028 -->
 > *Example*: In an implementation of the CLI, the `Help` attribute instances in the assembly created by compiling the example program in [§22.2.3](attributes.md#2223-positional-and-named-parameters) can be retrieved with the following program:
 >
-> <!-- Example: {template:"standalone-console", name:"RuntimeAttributeInstanceRetrieval", expectedOutput:["Type : HelpAttribute","Type : InterrogateHelpUrls"], additionalFiles:["HelpAttribute.cs"], executionArgs:["RuntimeAttributeInstanceRetrieval"]} -->
+> <!-- Example: {template:"standalone-console", name:"RuntimeAttributeInstanceRetrieval", expectedOutput:["Type : Microsoft.CodeAnalysis.EmbeddedAttribute", "Type : System.Runtime.CompilerServices.NullableAttribute", "Type : System.Runtime.CompilerServices.NullableContextAttribute", "Type : HelpAttribute","Type : InterrogateHelpUrls"], additionalFiles:["HelpAttribute.cs"], executionArgs:["RuntimeAttributeInstanceRetrieval"]} -->
 > ```csharp
 > public sealed class InterrogateHelpUrls
 > {

standard/basic-concepts.md

@@ -1024,7 +1024,7 @@ The behavior of the garbage collector can be controlled, to some degree, via sta
 > {
 >     static void Main()
 >     {
->         B b = new B(new A());
+>         B? b = new B(new A());
 >         b = null;
 >         GC.Collect();
 >         GC.WaitForPendingFinalizers();
@@ -1069,19 +1069,19 @@ The behavior of the garbage collector can be controlled, to some degree, via sta
 >
 > class B
 > {
->     public A Ref;
+>     public A? Ref;
 >
 >     ~B()
 >     {
 >         Console.WriteLine("Finalize instance of B");
->         Ref.F();
+>         Ref?.F();
 >     }
 > }
 >
 > class Test
 > {
->     public static A RefA;
->     public static B RefB;
+>     public static A? RefA;
+>     public static B? RefB;
 >
 >     static void Main()
 >     {

standard/lexical-structure.md

@@ -1025,7 +1025,7 @@ right_shift_assignment
 
 ### 6.5.1 General
 
-The pre-processing directives provide the ability to conditionally skip sections of compilation units, to report error and warning conditions, and to delineate distinct regions of source code.
+The pre-processing directives provide the ability to conditionally skip sections of compilation units, to report error and warning conditions, to delineate distinct regions of source code, and to set the nullable context.
 
 > *Note*: The term “pre-processing directives” is used only for consistency with the C and C++ programming languages. In C#, there is no separate pre-processing step; pre-processing directives are processed as part of the lexical analysis phase. *end note*
 
@@ -1041,6 +1041,7 @@ fragment PP_Kind
     | PP_Diagnostic
     | PP_Region
     | PP_Pragma
+    | PP_Nullable
     ;
 
 // Only recognised at the beginning of a line
@@ -1077,10 +1078,11 @@ The following pre-processing directives are available:
 - `#error`, which is used to issue errors ([§6.5.6](lexical-structure.md#656-diagnostic-directives)).
 - `#region` and `#endregion`, which are used to explicitly mark sections of source code ([§6.5.7](lexical-structure.md#657-region-directives)).
 - `#pragma`, which is used to specify optional contextual information to a compiler ([§6.5.9](lexical-structure.md#659-pragma-directives)).
+- `#nullable`, which is used to specify the nullable context (§Nullable-Directives).
 
 A pre-processing directive always occupies a separate line of source code and always begins with a `#` character and a pre-processing directive name. White space may occur before the `#` character and between the `#` character and the directive name.
 
-A source line containing a `#define`, `#undef`, `#if`, `#elif`, `#else`, `#endif`, `#line`, or `#endregion` directive can end with a single-line comment. Delimited comments (the `/* */` style of comments) are not permitted on source lines containing pre-processing directives.
+A source line containing a `#define`, `#undef`, `#if`, `#elif`, `#else`, `#endif`, `#line`, `#endregion`, or `#nullable` directive can end with a single-line comment. Delimited comments (the `/* */` style of comments) are not permitted on source lines containing pre-processing directives.
 
 Pre-processing directives are not part of the syntactic grammar of C#. However, pre-processing directives can be used to include or exclude sequences of tokens and can in that way affect the meaning of a C# program.
 
@@ -1506,6 +1508,40 @@ A `#line hidden` directive has no effect on the compilation unit and line number
 
 > *Note*: Although a *PP_Compilation_Unit_Name* might contain text that looks like an escape sequence, such text is not an escape sequence; in this context a ‘`\`’ character simply designates an ordinary backslash character. *end note*
 
+### §Nullable-Directives Nullable directives
+
+Nullable directives control the nullable contexts (§Nullable-Contexts), as described below.
+
+```ANTLR
+fragment PP_Nullable
+    : PP_Whitespace? '#' PP_Whitespace? 'nullable' PP_Whitespace PP_Nullable_Action
+        (PP_Whitespace PP_Nullable_Target)? PP_New_Line
+    ;
+fragment PP_Nullable_Action
+    : 'disable'
+    | 'enable'
+    | 'restore'
+    ;
+fragment PP_Nullable_Target
+    : 'warnings'
+    | 'annotations'
+    ;
+```
+
+A nullable directive sets the denoted nullable context(s) for subsequent lines of code, until another nullable directive overrides it, or until the end of the source code is reached. The effect of each form of nullable directive is, as follows:
+
+- `#nullable disable`: Sets both nullable contexts to “disabled”
+- `#nullable enable`: Sets both nullable contexts to “enabled”
+- `#nullable restore`: Restores both nullable contexts to the states specified by the external mechanism, if any
+- `#nullable disable annotations`: Sets the nullable annotation context to “disabled”
+- `#nullable enable annotations`: Sets the nullable annotation context to “enabled”
+- `#nullable restore annotations`: Restores the nullable annotation context to the state specified by the external mechanism, if any
+- `#nullable disable warnings`: Sets the nullable warning context to “disabled”
+- `#nullable enable warnings`: Sets the nullable warning context to “enabled”
+- `#nullable restore warnings`: Restores the nullable warning context to the state specified by the external mechanism, if any
+
+Disabling a nullable context that is already disabled has no effect. Likewise, enabling a nullable context that is already enabled has no effect.
+
 ### 6.5.9 Pragma directives
 
 The `#pragma` preprocessing directive is used to specify contextual information to a compiler.

tools/example-templates/standalone-console/Project.csproj

@@ -4,7 +4,7 @@
     <OutputType>Exe</OutputType>
     <TargetFramework>net6.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
-    <Nullable>disable</Nullable>
+    <Nullable>annotations</Nullable>
     <AssemblyName>$example-name</AssemblyName>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
   </PropertyGroup>