Fix examples where feasible

Towards dotnet#646

Author: jskeet

standard/classes.md

@@ -5114,8 +5114,7 @@ Finalizers are invoked automatically, and cannot be invoked explicitly. An insta
 
 > *Example*: The output of the example
 >
-> <!-- FIX: This works when I run it at the command-line, but when run under the tester tools, no output is produced. Perhaps the program terminates *before* the thread doing the cleanup runs! That is, the Wait doesn't really wait. -->
-> <!-- Incomplete$Example: {template:"standalone-console", name:"Finalizers1", inferOutput: true} -->
+> <!-- Example: {template:"standalone-console", name:"Finalizers1", inferOutput: true} -->
 > ```csharp
 > class A
 > {

standard/lexical-structure.md

@@ -87,7 +87,7 @@ If the following token is among this list, or an identifier in such a context, t
 >
 > will, according to this rule, be interpreted as a call to `F` with one argument, which is a call to a generic method `G` with two type arguments and one regular argument. The statements
 >
-> <!-- IncompleteExample: {template:"standalone-lib", name:"GrammarAmbiguities3"} -->
+> <!-- Incomplete$Example: {template:"standalone-lib", name:"GrammarAmbiguities3"} -->
 > ```csharp
 > F(G<A, B>7);
 > F(G<A, B>>7);
@@ -1311,8 +1311,7 @@ Any remaining conditional sections are skipped and no tokens, except those for p
 <!-- markdownlint-enable MD028 -->
 > *Example*: The following example illustrates how conditional compilation directives can nest:
 >
-> <!-- FIX: my thinking was to make CheckConsistency, WriteToLog, CommitHelper extension methods, but I could not get that to work. -->
-> <!-- Incomplete$Example: {template:"standalone-lib-without-using", name:"PreproConditionalCompilation", replaceEllipsis:true} -->
+> <!-- Example: {template:"standalone-lib-without-using", name:"PreproConditionalCompilation", replaceEllipsis:true, customEllipsisReplacements:["void CheckConsistency(){} void CommitHelper(){}"]} -->
 > ```csharp
 > #define Debug // Debugging on
 > #undef Trace // Tracing off
@@ -1335,7 +1334,7 @@ Any remaining conditional sections are skipped and no tokens, except those for p
 > Except for pre-processing directives, skipped source code is not subject to lexical analysis. For example, the following is valid despite the unterminated comment in the `#else` section:
 >
 > <!-- FIX: my thinking was to make CheckConsistency an extension method, but I could not get that to work. -->
-> <!-- Incomplete$Example: {template:"standalone-lib-without-using", name:"PreproInvalidSkippedSource", replaceEllipsis:true} -->
+> <!-- Example: {template:"standalone-lib-without-using", name:"PreproInvalidSkippedSource", replaceEllipsis:true, customEllipsisReplacements:["void CheckConsistency(){}"]} -->
 > ```csharp
 > #define Debug // Debugging on
 > class PurchaseTransaction

standard/statements.md

@@ -663,16 +663,14 @@ An `else` part is associated with the lexically nearest preceding `if` that is a
 
 > *Example*: Thus, an `if` statement of the form
 >
-> <!-- Incomplete$Example: {template:"standalone-console", name:"IfStatement1", expectedErrors:["x","x"], expectedWarnings:["x","x"]} -->
-> <!-- FIX: needs defs for x, y, F and G. -->
+> <!-- Example: {template:"code-in-main-without-using", name:"IfStatement1", additionalFiles:["PartialProgramWithFGxy.cs"]} -->
 > ```csharp
 > if (x) if (y) F(); else G();
 > ```
 >
 > is equivalent to
 >
-> <!-- Incomplete$Example: {template:"standalone-console", name:"IfStatement2", expectedErrors:["x","x"], expectedWarnings:["x","x"]} -->
-> <!-- FIX: needs defs for x, y, F and G. -->
+> <!-- Example: {template:"code-in-main-without-using", name:"IfStatement2", additionalFiles:["PartialProgramWithFGxy.cs"]} -->
 > ```csharp
 > if (x)
 > {
@@ -773,8 +771,7 @@ If the end point of the statement list of a switch section is reachable, a compi
 
 > *Example*: The example
 >
-> <!-- Incomplete$Example: {template:"standalone-console", name:"SwitchStatement1", expectedErrors:["x","x"], expectedWarnings:["x","x"]} -->
-> <!-- FIX: needs defs for i, CaseZero, CaseOne, and CaseOthers. -->
+> <!-- Example: {template:"code-in-main-without-using", name:"SwitchStatement1", additionalFiles:["PartialProgramForSwitch.cs"]} -->
 > ```csharp
 > switch (i)
 > {
@@ -792,8 +789,7 @@ If the end point of the statement list of a switch section is reachable, a compi
 >
 > is valid because no switch section has a reachable end point. Unlike C and C++, execution of a switch section is not permitted to “fall through” to the next switch section, and the example
 >
-> <!-- Incomplete$Example: {template:"standalone-console", name:"SwitchStatement2", expectedErrors:["CS0163","CS0163","CS8070"]} -->
-> <!-- FIX: needs defs for i, CaseZero, CaseZeroOrOne, and CaseAny. -->
+> <!-- Example: {template:"code-in-main-without-using", name:"SwitchStatement2", additionalFiles:["PartialProgramForSwitch.cs"], expectedErrors:["CS0163","CS0163","CS8070"]} -->
 > ```csharp
 > switch (i)
 > {
@@ -808,8 +804,7 @@ If the end point of the statement list of a switch section is reachable, a compi
 >
 > results in a compile-time error. When execution of a switch section is to be followed by execution of another switch section, an explicit `goto case` or `goto default` statement shall be used:
 >
-> <!-- Incomplete$Example: {template:"standalone-console", name:"SwitchStatement3"} -->
-> <!-- FIX: needs defs for i, CaseZero, CaseZeroOrOne, and CaseAny. -->
+> <!-- Example: {template:"code-in-main-without-using", name:"SwitchStatement3", additionalFiles:["PartialProgramForSwitch.cs"]} -->
 > ```csharp
 > switch (i)
 > {
@@ -831,8 +826,7 @@ Multiple labels are permitted in a *switch_section*.
 
 > *Example*: The example
 >
-> <!-- Incomplete$Example: {template:"standalone-console", name:"SwitchStatement4"} -->
-> <!-- FIX: needs defs for i, CaseZero, CaseOne, and CaseTwo. -->
+> <!-- Example: {template:"standalone-console", name:"SwitchStatement4", additionalFiles:["PartialProgramForSwitch.cs"]} -->
 > ```csharp
 > switch (i)
 > {
@@ -857,8 +851,7 @@ Multiple labels are permitted in a *switch_section*.
 <!-- markdownlint-enable MD028 -->
 > *Note*: The “no fall through” rule prevents a common class of bugs that occur in C and C++ when `break` statements are accidentally omitted. For example, the sections of the `switch` statement above can be reversed without affecting the behavior of the statement:
 >
-> <!-- Incomplete$Example: {template:"standalone-console", name:"SwitchStatement5"]} -->
-> <!-- FIX: needs defs for i, CaseZero, CaseZeroOrOne, and CaseAny. -->
+> <!-- Example: {template:"standalone-console", name:"SwitchStatement5", additionalFiles:["PartialProgramForSwitch.cs"]} -->
 > ```csharp
 > switch (i)
 > {
@@ -880,8 +873,7 @@ Multiple labels are permitted in a *switch_section*.
 <!-- markdownlint-enable MD028 -->
 > *Note*: The statement list of a switch section typically ends in a `break`, `goto case`, or `goto default` statement, but any construct that renders the end point of the statement list unreachable is permitted. For example, a `while` statement controlled by the Boolean expression `true` is known to never reach its end point. Likewise, a `throw` or `return` statement always transfers control elsewhere and never reaches its end point. Thus, the following example is valid:
 >
-> <!-- Incomplete$Example: {template:"standalone-console", name:"SwitchStatement6"} -->
-> <!-- FIX: needs defs for i, F. -->
+> <!-- Example: {template:"code-in-main", name:"SwitchStatement6", additionalFiles:["PartialProgramForSwitch.cs"]} -->
 > ```csharp
 > switch (i)
 > {
@@ -903,8 +895,7 @@ Multiple labels are permitted in a *switch_section*.
 <!-- markdownlint-enable MD028 -->
 > *Example*: The governing type of a `switch` statement can be the type `string`. For example:
 >
-> <!-- Incomplete$Example: {template:"standalone-console", name:"SwitchStatement7", expectedWarnings:["CS8321"]} -->
-> <!-- FIX: top-level must be a console, but then it has no named parent class type, so can't implement Do* as extension methods. -->
+> <!-- Example: {template:"code-in-class-lib", name:"SwitchStatement7", additionalFiles:["PartialClass1ForSwitch.cs"]} -->
 > ```csharp
 > void DoCommand(string command)
 > {

tools/ExampleTester/GeneratedExample.cs

@@ -152,6 +152,11 @@ bool ValidateOutput()
                     {
                         task.GetAwaiter().GetResult();
                     }
+                    // For some reason, we don't *actually* get the result of all finalizers
+                    // without this. We shouldn't need it (as relevant examples already have it) but
+                    // code that works outside the test harness doesn't work inside it.
+                    GC.Collect();
+                    GC.WaitForPendingFinalizers();
                 }
                 catch (TargetInvocationException outer)
                 {

tools/example-templates/additional-files/PartialClass1ForSwitch.cs

@@ -0,0 +1,7 @@
+partial class Class1
+{
+	void DoRun() {}
+	void DoSave() {}
+	void DoQuit() {}
+	void InvalidCommand(string command) {}
+}

tools/example-templates/additional-files/PartialProgramForSwitch.cs

@@ -0,0 +1,11 @@
+partial class Program
+{
+	static int i = -1;
+	static void CaseZero() {}
+	static void CaseOne() {}
+	static void CaseTwo() {}
+	static void CaseZeroOrOne() {}
+	static void CaseAny() {}
+	static void CaseOthers() {}
+	static void F() {}
+}

tools/example-templates/additional-files/PartialProgramWithFGxy.cs

@@ -0,0 +1,7 @@
+partial class Program
+{
+	static bool x = true;
+	static bool y = true;
+	static void F(){}
+	static void G(){}
+}

tools/example-templates/code-in-class-lib/Library.cs

@@ -11,7 +11,7 @@
 using System.Text;
 using System.Threading;
 
-class Class1
+partial class Class1
 {
     $example-code
 }

tools/example-templates/code-in-main-without-using/Program.cs

@@ -1,4 +1,4 @@
-class Program
+partial class Program
 {
     static void Main()
     {

tools/example-templates/code-in-main/Program.cs

@@ -11,7 +11,7 @@
 using System.Text;
 using System.Threading;
 
-class Program
+partial class Program
 {
     static void Main()
     {