Add a section about the generator to the README, and document some code.

src/README.md

@@ -3,6 +3,30 @@ Platform assemblies
 
 This directory contains the source code and build logic to build the platform assemblies.
 
+Generator
+=========
+
+The generator takes API definition files (most *.cs files in src/) as input,
+and generates the required binding code.
+
+There is one generator executable, based on IKVM, that's used to generate the
+binding code for all platforms.
+
+The generator relies heavily on binding attributes; all the binding attributes
+(that are not in the platform assembly) are compiled into a separate attribute
+assembly (Xamarin.[iOS|TVOS|WatchOS|Mac].BindingAttributes.dll).
+
+Since the platform assemblies (and thus all the binding attributes assemblies
+as well) reference each platform's BCL, those assemblies can't be loaded
+directly into the generator at runtime. In order to not make the generator
+code too complicated, all the attributes are also compiled into the generator
+executable, and then instantiated as mock-objects of the real attributes.
+
+The solution generator-ikvm.sln can be used to debug the generator. There are
+multiple run configurations (`ios-classic`, `ios-unified`, `tvos`, `watchos`,
+`mac-classic`, `mac-unified`, `mac-full`), each configured to execute the
+generator with the options for the corresponding profile.
+
 Conditional compilation
 =======================
 

src/generator-attribute-manager.cs

@@ -11,6 +11,8 @@ using System.Reflection;
 public static class AttributeManager
 {
 #if IKVM
+	// This method gets the System.Type for a IKVM.Reflection.Type to a System.Type.
+	// It knows about our mock attribute logic, so it will return the corresponding non-mocked System.Type for a mocked IKVM.Reflection.Type.
 	static System.Type ConvertType (Type type)
 	{
 		System.Type rv;
@@ -19,8 +21,10 @@ public static class AttributeManager
 		} else if (type.Assembly == TypeManager.SystemAssembly) {
 			rv = typeof (System.ComponentModel.EditorBrowsableAttribute).Assembly.GetType (type.FullName);
 		} else if (type.Assembly == TypeManager.BindingAssembly) {
+			// Types (attributes) in the binding assembly are mocked in the generator itself.
 			rv = typeof (TypeManager).Assembly.GetType (type.FullName);
 		} else if (type.Assembly == TypeManager.PlatformAssembly) {
+			// Types (attributes) in the platform assemblies are mocked in the generator itself.
 			var prefix = BindingTouch.NamespacePlatformPrefix;
 			var n = type.FullName;
 			if (!string.IsNullOrEmpty (prefix) && type.Namespace.StartsWith (prefix, System.StringComparison.Ordinal)) {
@@ -37,6 +41,8 @@ public static class AttributeManager
 		return rv;
 	}
 
+	// This method gets the IKVM.Reflection.Type for a System.Type.
+	// It knows about our mock attribute logic, so it will return the mocked IKVM.Reflection.Type for a mocked System.Type.
 	static Type ConvertType (System.Type type)
 	{
 		Type rv;
@@ -45,6 +51,8 @@ public static class AttributeManager
 		} else if (type.Assembly == typeof (System.ComponentModel.EditorBrowsableAttribute).Assembly) {
 			rv = TypeManager.SystemAssembly.GetType (type.FullName);
 		} else if (type.Assembly == typeof (TypeManager).Assembly) {
+			// Types (attributes) in the generator are mocked types from
+			// either the binding assembly or the platform assembly.
 			rv = TypeManager.BindingAssembly.GetType (type.FullName);
 			if (rv == null) {
 				string fullname;

src/generator-attributes.cs

@@ -7,6 +7,11 @@ using Type = IKVM.Reflection.Type;
 using System.Reflection;
 #endif
 
+//
+// All the attributes in this file are compiled into two binaries:
+// * Xamarin.*.Attributes.dll: this assembly references the platform assemblies (mscorlib, etc), and is used when compiling the API definition.
+// * bgen-ikvm.exe: when compiled into the generator itself, the attributes are used as mock objects to load the corresponding attributes from Xamarin.*.Attributes.dll.
+//
 
 //
 // ForcedTypeAttribute