Add comments on headers that gets parsed by Mono linker for whoever touches this next (#22054)

* Add comments on headers that gets parsed by Mono linker for whoever touches this next

* add more comments to the targets file

5 files changed, 34 insertions, 1 deletions

diff --git a/src/System.Private.CoreLib/CreateRuntimeRootILLinkDescriptorFile.targets b/src/System.Private.CoreLib/CreateRuntimeRootILLinkDescriptorFile.targets
index 967d71cb8d..e8eefb0f69 100644
--- a/src/System.Private.CoreLib/CreateRuntimeRootILLinkDescriptorFile.targets
+++ b/src/System.Private.CoreLib/CreateRuntimeRootILLinkDescriptorFile.targets
@@ -17,7 +17,14 @@
     <_ILLinkTasksDir Condition="'$(MSBuildRuntimeType)' == 'Core'">$(_ILLinkTasksToolsDir)/netcoreapp2.0/</_ILLinkTasksDir>
   </PropertyGroup>
 
-  <!-- Generates the xml root descriptor file for ILLink. The file contains roots required by the runtime. -->
+  <!-- 
+        Generates the xml root descriptor file for ILLink. The file contains roots required by the runtime. 
+        This gets generated by mono IL linker which lives in https://github.com/mono/linker 
+        If it fails, it'll spit out some cryptic error messages that's hard to debug.
+        You can debug it by setting /maxcpucount:1 in the msbuild command to force it to not spawn up a bunch
+        of child processes, and attach a debugger to msbuild. After that you can set a bp on the exception
+        you are seeing.
+  -->
   <UsingTask TaskName="CreateRuntimeRootILLinkDescriptorFile" AssemblyFile="$(_ILLinkTasksDir)ILLink.Tasks.dll" />
   <Target Name="_CreateILLinkRuntimeRootDescriptorFile"
           Inputs="$(_NamespaceFilePath);$(_MscorlibFilePath);$(_CortypeFilePath);$(_RexcepFilePath);$(_ILLinkTrimXmlFilePath)"
diff --git a/src/inc/cortypeinfo.h b/src/inc/cortypeinfo.h
index 8fdfe43c5f..6cc7325768 100644
--- a/src/inc/cortypeinfo.h
+++ b/src/inc/cortypeinfo.h
@@ -4,6 +4,14 @@
 
 // This describes information about the COM+ primitive types
 
+//
+// Note: This file gets parsed by the Mono IL Linker (https://github.com/mono/linker/) which may throw an exception during parsing.
+// Specifically, this (https://github.com/mono/linker/blob/master/corebuild/integration/ILLink.Tasks/CreateRuntimeRootDescriptorFile.cs) will try to 
+// parse this header, and it may throw an exception while doing that. If you edit this file and get a build failure on msbuild.exe D:\repos\coreclr\build.proj
+// you might want to check out the parser linked above.
+//
+
+
 #define NO_SIZE ((BYTE)-1)
 
 // TYPEINFO(type (CorElementType),  namespace, class,          size,                 gcType,         isArray,isPrim, isFloat,isModifier,isGenVariable)
diff --git a/src/vm/mscorlib.h b/src/vm/mscorlib.h
index a1341dd70f..7c5802a8b7 100644
--- a/src/vm/mscorlib.h
+++ b/src/vm/mscorlib.h
@@ -15,6 +15,12 @@
 //       examine vm\namespace.h. If it is not present, define it there and then proceed to use it below.
 //
 
+//
+// Note: This file gets parsed by the Mono IL Linker (https://github.com/mono/linker/) which may throw an exception during parsing.
+// Specifically, this (https://github.com/mono/linker/blob/master/corebuild/integration/ILLink.Tasks/CreateRuntimeRootDescriptorFile.cs) will try to 
+// parse this header, and it may throw an exception while doing that. If you edit this file and get a build failure on msbuild.exe D:\repos\coreclr\build.proj
+// you might want to check out the parser linked above.
+//
 
 // 
 // Note: The SM_* and IM_* are signatures defined in file:metasig.h using IM() and SM() macros.
diff --git a/src/vm/namespace.h b/src/vm/namespace.h
index 4395071559..7275584c03 100644
--- a/src/vm/namespace.h
+++ b/src/vm/namespace.h
@@ -4,6 +4,11 @@
 //
 // This file defines namespaces used by the runtime.
 //
+// Note: This file gets parsed by the Mono IL Linker (https://github.com/mono/linker/) which may throw an exception during parsing.
+// Specifically, this (https://github.com/mono/linker/blob/master/corebuild/integration/ILLink.Tasks/CreateRuntimeRootDescriptorFile.cs) will try to 
+// parse this header, and it may throw an exception while doing that. If you edit this file and get a build failure on msbuild.exe D:\repos\coreclr\build.proj
+// you might want to check out the parser linked above.
+//
 
 
 
diff --git a/src/vm/rexcep.h b/src/vm/rexcep.h
index 29f40cf37b..43b9f3aa7f 100644
--- a/src/vm/rexcep.h
+++ b/src/vm/rexcep.h
@@ -18,6 +18,13 @@
 // name for your HResult to the list below so it can be thrown from
 // within the EE and recognized in Interop scenarios.
 
+//
+// Note: This file gets parsed by the Mono IL Linker (https://github.com/mono/linker/) which may throw an exception during parsing.
+// Specifically, this (https://github.com/mono/linker/blob/master/corebuild/integration/ILLink.Tasks/CreateRuntimeRootDescriptorFile.cs) will try to 
+// parse this header, and it may throw an exception while doing that. If you edit this file and get a build failure on msbuild.exe D:\repos\coreclr\build.proj
+// you might want to check out the parser linked above.
+//
+
 
 // This is an exhaustive list of all exceptions that can be
 // thrown by the EE itself.  If you add to this list the IL spec