Add more comments (#83)

WoofWare.PawPrint.Domain/ConcreteType.fs

@@ -20,10 +20,16 @@ module FakeUnit =
 type ConcreteType<'typeGeneric when 'typeGeneric : comparison and 'typeGeneric :> IComparable<'typeGeneric>> =
     private
         {
+            /// Do not use this, because it's intended to be private; use the accessor `.Assembly : AssemblyName`
+            /// instead.
             _AssemblyName : AssemblyName
+            /// Do not use this, because it's intended to be private; use the accessor `.Definition` instead.
             _Definition : ComparableTypeDefinitionHandle
+            /// Do not use this, because it's intended to be private; use the accessor `.Name` instead.
             _Name : string
+            /// Do not use this, because it's intended to be private; use the accessor `.Namespace` instead.
             _Namespace : string
+            /// Do not use this, because it's intended to be private; use the accessor `.Generics` instead.
             _Generics : 'typeGeneric list
         }
 
@@ -48,17 +54,19 @@ type ConcreteType<'typeGeneric when 'typeGeneric : comparison and 'typeGeneric :
         member this.CompareTo (other : ConcreteType<'typeGeneric>) : int =
             let comp = this._AssemblyName.FullName.CompareTo other._AssemblyName.FullName
 
-            if comp = 0 then
-                let comp =
-                    (this._Definition :> IComparable<ComparableTypeDefinitionHandle>).CompareTo other._Definition
-
-                if comp = 0 then
-                    let thisGen = (this._Generics : 'typeGeneric list) :> IComparable<'typeGeneric list>
-                    thisGen.CompareTo other._Generics
-                else
-                    comp
-            else
+            if comp <> 0 then
                 comp
+            else
+
+            let comp =
+                (this._Definition :> IComparable<ComparableTypeDefinitionHandle>).CompareTo other._Definition
+
+            if comp <> 0 then
+                comp
+            else
+
+            let thisGen = (this._Generics : 'typeGeneric list) :> IComparable<'typeGeneric list>
+            thisGen.CompareTo other._Generics
 
     interface IComparable with
         member this.CompareTo other =

WoofWare.PawPrint.Domain/MethodSpec.fs

@@ -15,6 +15,17 @@ type MethodSpec =
         /// </summary>
         Method : MetadataToken
 
+        /// <summary>
+        /// The actual type arguments for generic instantiation.
+        /// </summary>
+        /// <example>
+        /// For <c>Volatile.Read&lt;System.IO.TextWriter&gt;</c>, the <c>Signature</c> is <c>[System.IO.TextWriter]</c>.
+        /// </example>
+        /// <remarks>
+        /// The contents might themselves be <c>TypeDefn.GenericMethodParameter</c>, for example.
+        /// This happens when the method is itself being called from within a generic method, and the generic parameters
+        /// of the spec are being instantiated with generic parameters from the caller.
+        /// </remarks>
         Signature : TypeDefn ImmutableArray
     }
 

WoofWare.PawPrint.Domain/TypeDefn.fs

@@ -55,6 +55,15 @@ module TypeMethodSignature =
             RequiredParameterCount = p.RequiredParameterCount
         }
 
+    let map<'a, 'b> (f : 'a -> 'b) (signature : TypeMethodSignature<'a>) : TypeMethodSignature<'b> =
+        {
+            Header = signature.Header
+            ReturnType = f signature.ReturnType
+            ParameterTypes = signature.ParameterTypes |> List.map f
+            GenericParameterCount = signature.GenericParameterCount
+            RequiredParameterCount = signature.RequiredParameterCount
+        }
+
 /// See I.8.2.2
 type PrimitiveType =
     | Boolean
@@ -134,7 +143,21 @@ type TypeDefn =
     | FromDefinition of ComparableTypeDefinitionHandle * assemblyFullName : string * SignatureTypeKind
     | GenericInstantiation of generic : TypeDefn * args : ImmutableArray<TypeDefn>
     | FunctionPointer of TypeMethodSignature<TypeDefn>
+    /// <summary>
+    /// A class/interface generic.
+    /// </summary>
+    /// <example>
+    /// The type <c>List&lt;T&gt;</c> has a generic parameter; an instance method on that <c>List</c> would refer to
+    /// <c>T</c> as <c>GenericTypeParameter 0</c>.
+    /// </example>
     | GenericTypeParameter of index : int
+    /// <summary>
+    /// A method generic.
+    /// </summary>
+    /// <example>
+    /// The method <c>List.map&lt;'a, 'b&gt;</c> takes two generic parameters; those are referred to as
+    /// <c>GenericMethodParameter 0</c> and <c>GenericMethodParameter 1</c> respectively.
+    /// </example>
     | GenericMethodParameter of index : int
     /// Not really a type: this indicates the *absence* of a return value.
     | Void