Refactor refout/refonly documentation

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

@@ -21,17 +21,7 @@ The **-refonly** option indicates that a reference assembly should be output ins
 
 ## 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 in cases where their removal doesn't observably impact compilation. If there are no <xref:System.Runtime.CompilerServices.InternalsVisibleToAttribute> 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)
+Reference assemblies are a special type of assembly that contain only the minimum amount of metadata required to represent the library's public API surface. They include declarations for all members that are significant when referencing an assembly in build tools, but exclude all member implementations and declarations of private members that have no observable impact on their API contract. For more information, see [Reference assemblies](../../../standard/assembly/reference-assemblies.md) in .NET Guide.
 
 The `-refonly` and [`-refout`](refout-compiler-option.md) options are mutually exclusive.
 

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

@@ -26,17 +26,7 @@ The filepath for the reference assembly. It should generally match that of the p
 
 ## 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 in cases where their removal doesn't observably impact compilation. If there are no <xref:System.Runtime.CompilerServices.InternalsVisibleToAttribute> 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)
+Reference assemblies are a special type of assembly that contain only the minimum amount of metadata required to represent the library's public API surface. They include declarations for all members that are significant when referencing an assembly in build tools, but exclude all member implementations and declarations of private members that have no observable impact on their API contract. For more information, see [Reference assemblies](../../../standard/assembly/reference-assemblies.md) in .NET Guide.
 
 The `-refout` and [`-refonly`](refonly-compiler-option.md) options are mutually exclusive.
 

docs/visual-basic/reference/command-line-compiler/refonly-compiler-option.md

@@ -23,11 +23,9 @@ The **-refonly** option indicates that the primary output of the compilation sho
 
 ## Remarks
 
-Visual Basic supports the `-refout` switch starting with version 15.3.
+Visual Basic supports the `-refonly` switch starting with version 15.3.
 
-Reference assemblies are metadata-only assemblies that contain metadata but no implementation code. They include type and member information for everything 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](xref:System.Runtime.CompilerServices.ReferenceAssemblyAttribute) 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 a reflection-only context). Tools that reflect on assemblies need to ensure they load reference assemblies as reflection-only; otherwise, the runtime throws a <xref:System.BadImageFormatException>.
+Reference assemblies are a special type of assembly that contain only the minimum amount of metadata required to represent the library's public API surface. They include declarations for all members that are significant when referencing an assembly in build tools, but exclude all member implementations and declarations of private members that have no observable impact on their API contract. For more information, see [Reference assemblies](../../../standard/assembly/reference-assemblies.md) in .NET Guide.
 
 The `-refonly` and [`-refout`](refout-compiler-option.md) options are mutually exclusive.
 

docs/visual-basic/reference/command-line-compiler/refout-compiler-option.md

@@ -30,9 +30,7 @@ The path and filename of the reference assembly. It should generally be in a sub
 
 Visual Basic supports the `-refout` switch starting with version 15.3.
 
-Reference assemblies are metadata-only assemblies that contain metadata but no implementation code. They include type and member information for everything except anonymous types. Their method bodies are replaced with a single `throw null` statement. The reason for using `throw null` method bodies (as opposed to no bodies) is so that PEVerify can run and pass (thus validating the completeness of the metadata).
-
-Reference assemblies include an assembly-level [ReferenceAssembly](xref:System.Runtime.CompilerServices.ReferenceAssemblyAttribute) attribute. This attribute may be specified in source (then the compiler won't need to synthesize it). Because of this attribute, runtimes refuse to load reference assemblies for execution (but they can still be loaded in a reflection-only context). Tools that reflect on assemblies need to ensure they load reference assemblies as reflection-only; otherwise, the runtime throws a <xref:System.BadImageFormatException>.
+Reference assemblies are a special type of assembly that contain only the minimum amount of metadata required to represent the library's public API surface. They include declarations for all members that are significant when referencing an assembly in build tools, but exclude all member implementations and declarations of private members that have no observable impact on their API contract. For more information, see [Reference assemblies](../../../standard/assembly/reference-assemblies.md) in .NET Guide.
 
 The `-refout` and [`-refonly`](refonly-compiler-option.md) options are mutually exclusive.