Add docstrings to custom reflection type records (#3)

WoofWare.PawPrint/Assembly.fs

@@ -11,8 +11,15 @@ open System.Reflection.PortableExecutable
 open Microsoft.Extensions.Logging
 open Microsoft.FSharp.Core
 
+/// <summary>
+/// Represents a .NET assembly definition.
+/// This is a strongly-typed representation of AssemblyDefinition from System.Reflection.Metadata.
+/// </summary>
 type AssemblyDefinition =
     {
+        /// <summary>
+        /// The fully specified name of the assembly, including name, version, culture, and public key token.
+        /// </summary>
         Name : AssemblyName
     }
 
@@ -23,30 +30,116 @@ module AssemblyDefinition =
             Name = assy.GetAssemblyName ()
         }
 
+/// <summary>
+/// Represents a fully parsed .NET assembly with all its metadata components.
+/// This serves as the main container for accessing assembly information in the PawPrint library.
+/// </summary>
 type DumpedAssembly =
     {
+        /// <summary>Logger for recording information about this assembly.</summary>
         Logger : ILogger
+
+        /// <summary>
+        /// Dictionary of all type definitions in this assembly, keyed by their handle.
+        /// </summary>
         TypeDefs : IReadOnlyDictionary<TypeDefinitionHandle, WoofWare.PawPrint.TypeInfo>
+
+        /// <summary>
+        /// Dictionary of all type references in this assembly, keyed by their handle.
+        /// </summary>
         TypeRefs : IReadOnlyDictionary<TypeReferenceHandle, WoofWare.PawPrint.TypeRef>
+
+        /// <summary>
+        /// Dictionary of all type specifications in this assembly, keyed by their handle.
+        /// Type specifications represent complex types like generic instantiations.
+        /// </summary>
         TypeSpecs : IReadOnlyDictionary<TypeSpecificationHandle, WoofWare.PawPrint.TypeSpec>
+
+        /// <summary>
+        /// Dictionary of all method definitions in this assembly, keyed by their handle.
+        /// </summary>
         Methods : IReadOnlyDictionary<MethodDefinitionHandle, WoofWare.PawPrint.MethodInfo>
+
+        /// <summary>
+        /// Dictionary of all member references in this assembly, keyed by their handle.
+        /// </summary>
         Members : IReadOnlyDictionary<MemberReferenceHandle, WoofWare.PawPrint.MemberReference<MetadataToken>>
+
+        /// <summary>
+        /// Dictionary of all field definitions in this assembly, keyed by their handle.
+        /// </summary>
         Fields : IReadOnlyDictionary<FieldDefinitionHandle, WoofWare.PawPrint.FieldInfo>
+
+        /// <summary>
+        /// The entry point method of the assembly, if one exists.
+        /// </summary>
         MainMethod : MethodDefinitionHandle option
-        /// Map of four-byte int token to metadata
+
+        /// <summary>
+        /// Dictionary mapping four-byte integer tokens to method definitions.
+        /// </summary>
         MethodDefinitions : ImmutableDictionary<int, MethodDefinition>
+
+        /// <summary>
+        /// Dictionary of all method specifications in this assembly, keyed by their handle.
+        /// Method specifications typically represent generic method instantiations.
+        /// </summary>
         MethodSpecs : ImmutableDictionary<MethodSpecificationHandle, MethodSpec>
+
+        /// <summary>
+        /// Function to resolve string tokens to their actual string values.
+        /// </summary>
         Strings : StringToken -> string
+
+        /// <summary>
+        /// Dictionary of all assembly references in this assembly, keyed by their handle.
+        /// </summary>
         AssemblyReferences : ImmutableDictionary<AssemblyReferenceHandle, WoofWare.PawPrint.AssemblyReference>
+
+        /// <summary>
+        /// Information about this assembly.
+        /// </summary>
         ThisAssemblyDefinition : AssemblyDefinition
+
+        /// <summary>
+        /// The root namespace of this assembly.
+        /// </summary>
         RootNamespace : Namespace
+
+        /// <summary>
+        /// Dictionary of all non-root namespaces in this assembly, keyed by their name components.
+        /// </summary>
         NonRootNamespaces : ImmutableDictionary<string list, Namespace>
-        // TODO: work out how to render all the strings up front, then drop this
+
+        /// <summary>
+        /// The PE reader for the underlying assembly file.
+        /// TODO: work out how to render all the strings up front, then drop this.
+        /// </summary>
         PeReader : PEReader
+
+        /// <summary>
+        /// Dictionary of all custom attributes in this assembly, keyed by their handle.
+        /// </summary>
         Attributes : ImmutableDictionary<CustomAttributeHandle, WoofWare.PawPrint.CustomAttribute>
+
+        /// <summary>
+        /// Dictionary of all exported types in this assembly, keyed by their handle.
+        /// </summary>
         ExportedTypes : ImmutableDictionary<ExportedTypeHandle, WoofWare.PawPrint.ExportedType>
+
+        /// <summary>
+        /// Internal lookup for exported types by namespace and name.
+        /// </summary>
         _ExportedTypesLookup : ImmutableDictionary<string option * string, WoofWare.PawPrint.ExportedType>
+
+        /// <summary>
+        /// Internal lookup for type references by namespace and name.
+        /// </summary>
         _TypeRefsLookup : ImmutableDictionary<string * string, WoofWare.PawPrint.TypeRef>
+
+        /// <summary>
+        /// Internal lookup for type definitions by namespace and name.
+        /// </summary>
         _TypeDefsLookup : ImmutableDictionary<string * string, WoofWare.PawPrint.TypeInfo>
     }
 

WoofWare.PawPrint/CustomAttribute.fs

@@ -2,9 +2,21 @@ namespace WoofWare.PawPrint
 
 open System.Reflection.Metadata
 
+/// <summary>
+/// Represents a custom attribute applied to a type, method, field, or other metadata entity.
+/// This is a strongly-typed representation of CustomAttribute from System.Reflection.Metadata.
+/// </summary>
 type CustomAttribute =
     {
+        /// <summary>
+        /// The metadata token handle that uniquely identifies this custom attribute in the assembly.
+        /// </summary>
         Handle : CustomAttributeHandle
+
+        /// <summary>
+        /// The constructor method used to create this custom attribute instance.
+        /// This token references the method that constructs the attribute.
+        /// </summary>
         Constructor : MetadataToken
     }
 

WoofWare.PawPrint/ExportedType.fs

@@ -3,17 +3,61 @@ namespace WoofWare.PawPrint
 open System.Reflection
 open System.Reflection.Metadata
 
+/// <summary>
+/// Represents the implementation details of an exported type.
+/// This discriminated union indicates whether the type is forwarded to another assembly
+/// or references another exported type.
+/// </summary>
 type ExportedTypeData =
+    /// <summary>
+    /// Indicates the type is forwarded to another assembly.
+    /// Type forwarders are used to redirect type references to implementations in other assemblies.
+    /// </summary>
     | ForwardsTo of AssemblyReferenceHandle
+
+    /// <summary>
+    /// Indicates the type references another exported type within the assembly.
+    /// This is often used for nested types.
+    /// </summary>
     | NonForwarded of ExportedTypeHandle
 
+/// <summary>
+/// Represents a type exported from an assembly.
+/// Exported types are types that are defined in one module but made visible
+/// at the assembly level, or types that are forwarded to another assembly.
+/// </summary>
 type ExportedType =
     {
+        /// <summary>
+        /// The metadata token handle that uniquely identifies this exported type.
+        /// </summary>
         Handle : ExportedTypeHandle
+
+        /// <summary>
+        /// The name of the exported type.
+        /// </summary>
         Name : string
+
+        /// <summary>
+        /// The namespace containing the exported type, if any.
+        /// None if the type is not in a namespace.
+        /// </summary>
         Namespace : string option
+
+        /// <summary>
+        /// The metadata handle for the namespace definition containing this type.
+        /// </summary>
         NamespaceDefn : NamespaceDefinitionHandle
+
+        /// <summary>
+        /// The type attributes (visibility, inheritance characteristics, etc.) for this exported type.
+        /// </summary>
         TypeAttrs : TypeAttributes
+
+        /// <summary>
+        /// The implementation details of this exported type, indicating whether it forwards
+        /// to another assembly or references another exported type.
+        /// </summary>
         Data : ExportedTypeData
     }
 

WoofWare.PawPrint/FieldInfo.fs

@@ -2,12 +2,34 @@ namespace WoofWare.PawPrint
 
 open System.Reflection.Metadata
 
+/// <summary>
+/// Represents detailed information about a field in a .NET assembly.
+/// This is a strongly-typed representation of FieldDefinition from System.Reflection.Metadata.
+/// </summary>
 type FieldInfo =
     {
+        /// <summary>
+        /// The metadata token handle that uniquely identifies this field in the assembly.
+        /// </summary>
         Handle : FieldDefinitionHandle
+
+        /// <summary>The name of the field.</summary>
         Name : string
+
+        /// <summary>
+        /// The type that declares this field.
+        /// </summary>
         DeclaringType : TypeDefinitionHandle
+
+        /// <summary>
+        /// The type of the field.
+        /// </summary>
         Signature : TypeDefn
+
+        /// <summary>
+        /// The attributes applied to this field, including visibility, static/instance,
+        /// literal, and other characteristics.
+        /// </summary>
         Attributes : System.Reflection.FieldAttributes
     }
 

WoofWare.PawPrint/MethodInfo.fs

@@ -8,10 +8,25 @@ open System.Reflection.Metadata
 open System.Reflection.PortableExecutable
 open Microsoft.Extensions.Logging
 
+/// <summary>
+/// Represents information about a method parameter.
+/// Corresponds to Parameter in System.Reflection.Metadata.
+/// </summary>
 type Parameter =
     {
+        /// <summary>The name of the parameter.</summary>
         Name : string
+
+        /// <summary>
+        /// The default value of the parameter, if one is specified.
+        /// This is used for optional parameters.
+        /// </summary>
         DefaultValue : Constant
+
+        /// <summary>
+        /// The position of the parameter in the parameter list.
+        /// For instance methods, index 0 is the 'this' parameter.
+        /// </summary>
         SequenceNumber : int
     }
 
@@ -30,9 +45,19 @@ module Parameter =
         )
         |> ImmutableArray.CreateRange
 
+/// <summary>
+/// Represents a generic type or method parameter definition.
+/// Corresponds to GenericParameter in System.Reflection.Metadata.
+/// </summary>
 type GenericParameter =
     {
+        /// <summary>The name of the generic parameter (e.g., 'T', 'TKey', etc.).</summary>
         Name : string
+
+        /// <summary>
+        /// The zero-based index of the generic parameter in the generic parameter list.
+        /// For example, in Dictionary<TKey, TValue>, TKey has index 0 and TValue has index 1.
+        /// </summary>
         SequenceNumber : int
     }
 
@@ -54,20 +79,66 @@ module GenericParameter =
         )
         |> ImmutableArray.CreateRange
 
+/// <summary>
+/// Represents detailed information about a method in a .NET assembly.
+/// This is a strongly-typed representation of MethodDefinition from System.Reflection.Metadata.
+/// </summary>
 type MethodInfo =
     {
+        /// <summary>
+        /// The type that declares this method, along with its assembly information.
+        /// </summary>
         DeclaringType : TypeDefinitionHandle * AssemblyName
+
+        /// <summary>
+        /// The metadata token handle that uniquely identifies this method in the assembly.
+        /// </summary>
         Handle : MethodDefinitionHandle
+
+        /// <summary>The name of the method.</summary>
         Name : string
-        /// also stores the offset of this instruction
+
+        /// <summary>
+        /// The IL instructions that comprise the method body, along with their offset positions.
+        /// Each tuple contains the instruction and its offset in the method body.
+        /// </summary>
         Instructions : (IlOp * int) list
-        /// inverted Instructions: a mapping of program counter to op
+
+        /// <summary>
+        /// A map from instruction offset (program counter) to the corresponding IL operation.
+        /// This is the inverse of Instructions for efficient lookup.
+        /// </summary>
         Locations : Map<int, IlOp>
+
+        /// <summary>
+        /// The parameters of this method.
+        /// </summary>
         Parameters : Parameter ImmutableArray
+
+        /// <summary>
+        /// The generic type parameters defined by this method, if any.
+        /// </summary>
         Generics : GenericParameter ImmutableArray
+
+        /// <summary>
+        /// The signature of the method, including return type and parameter types.
+        /// </summary>
         Signature : TypeMethodSignature<TypeDefn>
+
+        /// <summary>
+        /// Whether this method is implemented as a platform invoke (P/Invoke) to unmanaged code.
+        /// </summary>
         IsPinvokeImpl : bool
+
+        /// <summary>
+        /// Whether local variables in this method should be initialized to their default values.
+        /// This corresponds to the localsinit flag in the method header.
+        /// </summary>
         LocalsInit : bool
+
+        /// <summary>
+        /// Whether this method is static (true) or an instance method (false).
+        /// </summary>
         IsStatic : bool
     }
 

WoofWare.PawPrint/Tokens.fs

@@ -3,36 +3,70 @@ namespace WoofWare.PawPrint
 open System.Reflection.Metadata
 open System.Reflection.Metadata.Ecma335
 
+/// <summary>
+/// Represents a strongly-typed metadata token which can reference various elements in the assembly metadata.
+/// This discriminated union provides type-safe handling of metadata tokens with specific handle types.
+/// </summary>
 type MetadataToken =
+    /// <summary>Method implementation token, specifying how a virtual method is implemented.</summary>
     | MethodImplementation of MethodImplementationHandle
+    /// <summary>Method definition token, identifying a method defined in this assembly.</summary>
     | MethodDef of MethodDefinitionHandle
+    /// <summary>Method specification token, typically for generic method instantiations.</summary>
     | MethodSpecification of MethodSpecificationHandle
+    /// <summary>Member reference token, for references to fields or methods in other modules/assemblies.</summary>
     | MemberReference of MemberReferenceHandle
+    /// <summary>Type reference token, for references to types in other modules/assemblies.</summary>
     | TypeReference of TypeReferenceHandle
+    /// <summary>Assembly reference token, identifying an external assembly.</summary>
     | AssemblyReference of AssemblyReferenceHandle
+    /// <summary>Type specification token, for representing complex types like generic instantiations.</summary>
     | TypeSpecification of TypeSpecificationHandle
+    /// <summary>Type definition token, identifying a type defined in this assembly.</summary>
     | TypeDefinition of TypeDefinitionHandle
+    /// <summary>Field definition token, identifying a field defined in this assembly.</summary>
     | FieldDefinition of FieldDefinitionHandle
+    /// <summary>Parameter token, identifying a parameter of a method.</summary>
     | Parameter of ParameterHandle
+    /// <summary>Interface implementation token, mapping an implementation to an interface method.</summary>
     | InterfaceImplementation of InterfaceImplementationHandle
+    /// <summary>Exported type token, identifying a type exported from this assembly.</summary>
     | ExportedType of ExportedTypeHandle
+    /// <summary>Standalone signature token, for method signatures not attached to any method.</summary>
     | StandaloneSignature of StandaloneSignatureHandle
+    /// <summary>Event definition token, identifying an event defined in this assembly.</summary>
     | EventDefinition of EventDefinitionHandle
+    /// <summary>Constant token, representing a constant value stored in metadata.</summary>
     | Constant of ConstantHandle
+    /// <summary>Custom attribute token, identifying an attribute applied to a metadata element.</summary>
     | CustomAttribute of CustomAttributeHandle
+    /// <summary>Security attribute token, for declarative security attributes.</summary>
     | DeclarativeSecurityAttribute of DeclarativeSecurityAttributeHandle
+    /// <summary>Property definition token, identifying a property defined in this assembly.</summary>
     | PropertyDefinition of PropertyDefinitionHandle
+    /// <summary>Module reference token, for references to other modules in the same assembly.</summary>
     | ModuleReference of ModuleReferenceHandle
+    /// <summary>Assembly file token, identifying a file that is part of this assembly.</summary>
     | AssemblyFile of AssemblyFileHandle
+    /// <summary>Manifest resource token, identifying a resource embedded in this assembly.</summary>
     | ManifestResource of ManifestResourceHandle
+    /// <summary>Generic parameter token, identifying a generic type or method parameter.</summary>
     | GenericParameter of GenericParameterHandle
+    /// <summary>Generic parameter constraint token, identifying a constraint on a generic parameter.</summary>
     | GenericParameterConstraint of GenericParameterConstraintHandle
+    /// <summary>Document token, used in debugging information.</summary>
     | Document of DocumentHandle
+    /// <summary>Method debug information token, for debugging metadata about a method.</summary>
     | MethodDebugInformation of MethodDebugInformationHandle
+    /// <summary>Local scope token, identifying a scope within a method body.</summary>
     | LocalScope of LocalScopeHandle
+    /// <summary>Local variable token, identifying a local variable in a method.</summary>
     | LocalVariable of LocalVariableHandle
+    /// <summary>Local constant token, identifying a local constant in a method.</summary>
     | LocalConstant of LocalConstantHandle
+    /// <summary>Import scope token, used in debugging information for namespace imports.</summary>
     | ImportScope of ImportScopeHandle
+    /// <summary>Custom debug information token, for user-defined debugging metadata.</summary>
     | CustomDebugInformation of CustomDebugInformationHandle
 
 [<RequireQualifiedAccess>]

WoofWare.PawPrint/TypeDefn.fs

@@ -4,12 +4,35 @@ open System.Collections.Immutable
 open System.Reflection.Metadata
 open System.Reflection.Metadata.Ecma335
 
+/// <summary>
+/// Represents a method signature with type parameters.
+/// Corresponds to MethodSignature in System.Reflection.Metadata.
+/// </summary>
 type TypeMethodSignature<'Types> =
     {
+        /// <summary>
+        /// Contains calling convention and other method attributes encoded in the metadata.
+        /// </summary>
         Header : SignatureHeader
+
+        /// <summary>
+        /// The types of all parameters of the method.
+        /// </summary>
         ParameterTypes : 'Types list
+
+        /// <summary>
+        /// The number of generic type parameters defined by this method.
+        /// </summary>
         GenericParameterCount : int
+
+        /// <summary>
+        /// The number of required parameters (non-optional parameters).
+        /// </summary>
         RequiredParameterCount : int
+
+        /// <summary>
+        /// The return type of the method.
+        /// </summary>
         ReturnType : 'Types
     }
 

WoofWare.PawPrint/TypeInfo.fs

@@ -8,8 +8,15 @@ open System.Reflection.PortableExecutable
 open Microsoft.Extensions.Logging
 open Microsoft.FSharp.Core
 
+/// <summary>
+/// Represents a method specification, which provides information about a method,
+/// particularly for generic method instantiations.
+/// </summary>
 type MethodSpec =
     {
+        /// <summary>
+        /// The token that identifies the method being specialized.
+        /// </summary>
         Method : MetadataToken
     }
 
@@ -31,16 +38,54 @@ type MethodImplParsed =
     | MethodImplementation of MethodImplementationHandle
     | MethodDefinition of MethodDefinitionHandle
 
+/// <summary>
+/// Represents detailed information about a type definition in a .NET assembly.
+/// This is a strongly-typed representation of TypeDefinition from System.Reflection.Metadata.
+/// </summary>
 type TypeInfo =
     {
+        /// <summary>The namespace containing the type.</summary>
         Namespace : string
+
+        /// <summary>The name of the type.</summary>
         Name : string
+
+        /// <summary>
+        /// All methods defined within this type.
+        /// </summary>
         Methods : WoofWare.PawPrint.MethodInfo list
+
+        /// <summary>
+        /// Method implementation mappings for this type, often used for interface implementations
+        /// or overriding virtual methods from base classes.
+        /// </summary>
         MethodImpls : ImmutableDictionary<MethodImplementationHandle, MethodImplParsed>
+
+        /// <summary>
+        /// Fields defined in this type.
+        /// </summary>
         Fields : WoofWare.PawPrint.FieldInfo list
+
+        /// <summary>
+        /// The base type that this type inherits from, or None for types that don't have a base type
+        /// (like System.Object).
+        /// </summary>
         BaseType : BaseTypeInfo option
+
+        /// <summary>
+        /// Attributes applied to this type, such as visibility, inheritance characteristics,
+        /// special handling, and other flags.
+        /// </summary>
         TypeAttributes : TypeAttributes
+
+        /// <summary>
+        /// Custom attributes applied to this type.
+        /// </summary>
         Attributes : WoofWare.PawPrint.CustomAttribute list
+
+        /// <summary>
+        /// The metadata token handle that uniquely identifies this type in the assembly.
+        /// </summary>
         TypeDefHandle : TypeDefinitionHandle
     }
 

WoofWare.PawPrint/TypeRef.fs

@@ -2,10 +2,25 @@ namespace WoofWare.PawPrint
 
 open System.Reflection.Metadata
 
+/// <summary>
+/// Represents a type reference in a .NET assembly metadata.
+/// This corresponds to a TypeReferenceHandle in System.Reflection.Metadata.
+/// </summary>
 type TypeRef =
     {
+        /// <summary>The simple name of the referenced type (without namespace).</summary>
         Name : string
+
+        /// <summary>The namespace of the referenced type, or empty string for nested types.</summary>
         Namespace : string
+
+        /// <summary>
+        /// The scope of the type reference. This can be:
+        /// - AssemblyReference token: When the type is defined in another assembly
+        /// - ModuleReference token: When the type is defined in another module of the same assembly
+        /// - TypeReference token: When the type is a nested type
+        /// - ModuleDefinition token: When the type is defined in the current module
+        /// </summary>
         ResolutionScope : WoofWare.PawPrint.MetadataToken
     }
 

WoofWare.PawPrint/TypeSpec.fs

@@ -2,9 +2,22 @@ namespace WoofWare.PawPrint
 
 open System.Reflection.Metadata
 
+/// <summary>
+/// Represents a type specification in assembly metadata.
+/// Type specifications describe complex types like generic instantiations,
+/// arrays, pointers, and other composite types.
+/// </summary>
 type TypeSpec =
     {
+        /// <summary>
+        /// The metadata token handle that uniquely identifies this type specification.
+        /// </summary>
         Handle : TypeSpecificationHandle
+
+        /// <summary>
+        /// The full type definition/signature of this type specification.
+        /// This contains all the details about the composite type structure.
+        /// </summary>
         Signature : TypeDefn
     }