Document new reference assembly compiler options (dotnet#2857)

* Document new reference assembly compiler options

Generate reference assemblies along with primary assembly, or instead of
primary assembly.

* updates per initial feedback

* respond to feedback.

* respond to feedback

Author: BillWagner

docs/csharp/language-reference/compiler-options/listed-alphabetically.md

@@ -79,6 +79,8 @@ The following compiler options are sorted alphabetically. For a categorical list
 |[/preferreduilang](../../../csharp/language-reference/compiler-options/preferreduilang-compiler-option.md)|Specifies the language to be used for compiler output.|  
 |[/recurse](../../../csharp/language-reference/compiler-options/recurse-compiler-option.md)|Includes all files in the current directory and subdirectories according to the wildcard specifications.|  
 |[/reference](../../../csharp/language-reference/compiler-options/reference-compiler-option.md)|References metadata from the specified assembly files.|  
+|[/refout](refout-compiler-option.md)|Generate a reference assembly in addition to the primary assembly.|  
+|[/refonly](refonly-compiler-option.md)|Generate a reference assembly instead of a primary assembly.|  
 |[/resource](../../../csharp/language-reference/compiler-options/resource-compiler-option.md)|Embeds the specified resource.|  
 |/ruleset:\<file>|Specify a ruleset file that disables specific diagnostics.|  
 |[/subsystemversion](../../../csharp/language-reference/compiler-options/subsystemversion-compiler-option.md)|Specifies the minimum version of the subsystem that the executable file can use.|  

docs/csharp/language-reference/compiler-options/listed-by-category.md

@@ -49,6 +49,8 @@ The following compiler options are sorted by category. For an alphabetical list,
 |[/pdb](../../../csharp/language-reference/compiler-options/pdb-compiler-option.md)|Specifies the file name and location of the .pdb file.|  
 |[/platform](../../../csharp/language-reference/compiler-options/platform-compiler-option.md)|Specify the output platform.|  
 |[/preferreduilang](../../../csharp/language-reference/compiler-options/preferreduilang-compiler-option.md)|Specify a language for compiler output.|  
+|[/refout](refout-compiler-option.md)|Generate a reference assembly in addition to the primary assembly.|  
+|[/refonly](refonly-compiler-option.md)|Generate a reference assembly instead of a primary assembly.|  
 |[/target](../../../csharp/language-reference/compiler-options/target-compiler-option.md)|Specifies the format of the output file using one of five options: [/target:appcontainerexe](../../../csharp/language-reference/compiler-options/target-appcontainerexe-compiler-option.md), [/target:exe](../../../csharp/language-reference/compiler-options/target-exe-compiler-option.md), [/target:library](../../../csharp/language-reference/compiler-options/target-library-compiler-option.md), [/target:module](../../../csharp/language-reference/compiler-options/target-module-compiler-option.md), [/target:winexe](../../../csharp/language-reference/compiler-options/target-winexe-compiler-option.md), or [/target:winmdobj](../../../csharp/language-reference/compiler-options/target-winmdobj-compiler-option.md).|  
 |/modulename:\<string>|Specify the name of the source module|  
 

docs/csharp/language-reference/compiler-options/refonly-compiler-option.md

@@ -0,0 +1,47 @@
+---
+title: "-refonly (C# Compiler Options)"
+ms.date: "2017-07-08"
+ms.prod: .net
+ms.technology: 
+  - "devlang-csharp"
+ms.topic: "article"
+f1_keywords: 
+  - "/refonly"
+dev_langs: 
+  - "CSharp"
+helpviewer_keywords: 
+  - "/refonly compiler option [C#]"
+  - "-refonly compiler option [C#]"
+author: "BillWagner"
+ms.author: "wiwagn"
+---
+
+# /refonly (C# Compiler Options)
+
+The **/refonly** The /refonly option indicates that a reference assembly should be output instead of an implementation assembly, as the primary output. The `/refonly` parameter silently disables outputting PDBs, as reference assemblies cannot be executed.
+
+## Syntax
+
+```console
+/refonly
+```
+
+## Remarks
+
+Metadata-only assemblies have their method bodies replaced with a single `throw null` body, but include all members except anonymous types. The reason for using `throw null` bodies (as opposed to no bodies) is so that PEVerify could run and pass (thus validating the completeness of the metadata).
+
+Reference assemblies include an assembly-level `ReferenceAssembly` attribute. This attribute may be specified in source (then the compiler won't need to synthesize it). Because of this attribute, runtimes will refuse to load reference assemblies for execution (but they can still be loaded in reflection-only mode). Tools that reflect on assemblies need to ensure they load reference assemblies as reflection-only, otherwise they will receive a typeload error from the runtime.
+
+Reference assemblies further remove metadata (private members) from metadata-only assemblies:
+
+- A reference assembly only has references for what it needs in the API surface. The real assembly may have additional references related to specific implementations. For instance, the reference assembly for `class C { private void M() { dynamic d = 1; ... } }` does not reference any types required for `dynamic`.
+- Private function-members (methods, properties, and events) are removed. If there are no `InternalsVisibleTo` attributes, do the same for internal function-members.
+- But all types (including private or nested types) are kept in reference assemblies. All attributes are kept (even internal ones).
+- All virtual methods are kept. Explicit interface implementations are kept. Explicitly implemented properties and events are kept, as their accessors are virtual (and are therefore kept).
+- All fields of a struct are kept. (This is a candidate for post-C#-7.1 refinement)
+
+The `/refonly` and [`/refout`](refout-compiler-option.md) options are mutually exclusive.
+
+## See also
+ [C# Compiler Options](../../../csharp/language-reference/compiler-options/index.md)   
+ [Managing Project and Solution Properties](/visualstudio/ide/managing-project-and-solution-properties)

docs/csharp/language-reference/compiler-options/refout-compiler-option.md

@@ -0,0 +1,53 @@
+---
+title: "-refout (C# Compiler Options)"
+ms.date: "2017-08-08"
+ms.prod: .net
+ms.technology: 
+  - "devlang-csharp"
+ms.topic: "article"
+f1_keywords: 
+  - "/refout"
+dev_langs: 
+  - "CSharp"
+helpviewer_keywords: 
+  - "refout compiler option [C#]"
+  - "/refout compiler option [C#]"
+  - "-refout compiler option [C#]"
+author: "BillWagner"
+ms.author: "wiwagn"
+---
+
+# /refout (C# Compiler Options)
+
+The **/refout** option specifies a file path where the reference assembly should be output. This translates to `metadataPeStream` in the Emit API.
+
+## Syntax
+
+```console
+/refout:filepath
+```
+
+## Arguments
+
+ `filepath`
+The filepath for the reference assembly. It should generally match that of the primary assembly. The recommended convention (used by MSBuild) is to place the reference assembly in a "ref/" sub-folder relative to the primary assembly.
+
+## Remarks
+
+Metadata-only assemblies have their method bodies replaced with a single `throw null` body, but include all members except anonymous types. The reason for using `throw null` bodies (as opposed to no bodies) is so that PEVerify could run and pass (thus validating the completeness of the metadata).
+
+Reference assemblies include an assembly-level `ReferenceAssembly` attribute. This attribute may be specified in source (then the compiler won't need to synthesize it). Because of this attribute, runtimes will refuse to load reference assemblies for execution (but they can still be loaded in reflection-only mode). Tools that reflect on assemblies need to ensure they load reference assemblies as reflection-only, otherwise they will receive a typeload error from the runtime.
+
+Reference assemblies further remove metadata (private members) from metadata-only assemblies:
+
+- A reference assembly only has references for what it needs in the API surface. The real assembly may have additional references related to specific implementations. For instance, the reference assembly for `class C { private void M() { dynamic d = 1; ... } }` does not reference any types required for `dynamic`.
+- Private function-members (methods, properties, and events) are removed. If there are no `InternalsVisibleTo` attributes, do the same for internal function-members.
+- But all types (including private or nested types) are kept in reference assemblies. All attributes are kept (even internal ones).
+- All virtual methods are kept. Explicit interface implementations are kept. Explicitly implemented properties and events are kept, as their accessors are virtual (and are therefore kept).
+- All fields of a struct are kept. (This is a candidate for post-C#-7.1 refinement)
+
+The `/refout` and [`/refonly`](refonly-compiler-option.md) options are mutually exclusive.
+
+## See Also
+ [C# Compiler Options](../../../csharp/language-reference/compiler-options/index.md)   
+ [Managing Project and Solution Properties](/visualstudio/ide/managing-project-and-solution-properties)

docs/csharp/language-reference/compiler-options/toc.md

@@ -40,6 +40,8 @@
 ### [-preferreduilang (C# Compiler Options)](preferreduilang-compiler-option.md)
 ### [-recurse (C# Compiler Options)](recurse-compiler-option.md)
 ### [-reference (C# Compiler Options)](reference-compiler-option.md)
+### [-refout (C# Compiler Options)](refout-compiler-option.md)
+### [-refonly (C# Compiler Options)](refonlye-compiler-option.md)
 ### [-resource (C# Compiler Options)](resource-compiler-option.md)
 ### [-subsystemversion (C# Compiler Options)](subsystemversion-compiler-option.md)
 ### [-target (C# Compiler Options)](target-compiler-option.md)