Add note about IlcScanReflection to the native aot docs (#90765)

jkotas · web-flow · commit 8848123e140b · 2023-08-18T12:58:26.000-07:00
Fixes #90171
diff --git a/src/coreclr/nativeaot/BuildIntegration/Microsoft.NETCore.Native.targets b/src/coreclr/nativeaot/BuildIntegration/Microsoft.NETCore.Native.targets
@@ -248,7 +248,7 @@ The .NET Foundation licenses this file to you under the MIT license.
       <IlcArg Include="@(RuntimeHostConfigurationOption->'--runtimeknob:%(Identity)=%(Value)')" />
       <IlcArg Include="--runtimeknob:RUNTIME_IDENTIFIER=$(RuntimeIdentifier)" />
       <IlcArg Condition="$(ServerGarbageCollection) == 'true'" Include="--runtimeopt:gcServer=1" />
-      <IlcArg Condition="$(IlcGenerateCompleteTypeMetadata) == 'true' and $(IlcDisableReflection) != 'true'" Include="--completetypemetadata" />
+      <IlcArg Condition="$(IlcGenerateCompleteTypeMetadata) == 'true'" Include="--completetypemetadata" />
       <IlcArg Condition="$(StackTraceSupport) != 'false'" Include="--stacktracedata" />
       <IlcArg Condition="$(IlcScanReflection) != 'false' and $(IlcDisableReflection) != 'true'" Include="--scanreflection" />
       <IlcArg Condition="$(IlcFoldIdenticalMethodBodies) == 'true'" Include="--methodbodyfolding" />
diff --git a/src/coreclr/nativeaot/docs/reflection-free-mode.md b/src/coreclr/nativeaot/docs/reflection-free-mode.md
@@ -1,6 +1,6 @@
 # Reflection-free mode
 
-Reflection-free mode is a mode of the NativeAOT compiler and runtime that greatly reduces the functionality of the reflection APIs and brings a couple interesting benefits as a result. The benefits of this mode are:
+Reflection-free mode is a highly experimental mode of the NativeAOT compiler and runtime that greatly reduces the functionality of the reflection APIs and brings a couple interesting benefits as a result. The benefits of this mode are:
 
 * Greatly reduced size of self contained deployments - a fully self-contained "Hello world" style app compiles to a 1 MB file (on x64) with _no dependencies_.
 * Reduced working set and better code locality - parts of the program are more tightly packed together.
@@ -16,8 +16,6 @@ To enable reflection-free mode in a project that is already using NativeAOT, add
 </PropertyGroup>
 ```
 
-(More switches are documented in the [Optimizing NativeAOT](optimizing.md) document.)
-
 ## What's different at compile time with reflection disabled
 
 When reflection is disabled, the AOT compiler stops emitting data structures that are required to make reflection work at runtime and stops enforcing policies that makes the code more reflection friendly.
@@ -74,21 +72,17 @@ To achieve similar result for when querying for ``Assembly`` (will instead give
 
 And here for CustomAttributes (will return an empty array):
 
-
 ```xml
   <ItemGroup>
     <RuntimeHostConfigurationOption Include="Switch.System.Reflection.Disabled.DoNotThrowForAttributes" Value="true" />
   </ItemGroup>
 ```
 
-Note:
-
-To make ``NativeLibrary`` API, and on the same occasion``Socket``, to work, you'll need:
+## Internal implementation
 
-```xml
-  <ItemGroup>
-    <RuntimeHostConfigurationOption Include="Switch.System.Reflection.Disabled.DoNotThrowForAssembly" Value="true" />
-    <RuntimeHostConfigurationOption Include="Switch.System.Reflection.Disabled.DoNotThrowForAttributes" Value="true" />
-  </ItemGroup>
-```
+The reflection-free mode is implemented as a collection of features that can be controlled individually via the AOT compiler command line options for experiments and troubleshooting, including:
+- `--scanreflection` (also exposed as `IlcScanReflection` build property): Infer reflection usage by code analysis. This feature is disabled for reflection-free mode.
+- `--reflectiondata:none`: Disables generation of reflection data.
+- `--feature:System.Collections.Generic.DefaultComparers=false`: Disables `EqualityComparer<T>.Default` and `Comparer<T>.Default` optimizations that are based on reflection.
 
+The complete set of individual features that the reflection-free mode is composed from currently can be found by looking for `IlcDisableReflection` in [Microsoft.NETCore.Native.targets](../BuildIntegration/Microsoft.NETCore.Native.targets).
