Add a few more options to help with "feature-completing" a set of bindings

Directory.Build.targets

@@ -37,7 +37,7 @@
     <PackageReference Update="libClangSharp" Version="13.0.0-beta1" />
     <PackageReference Update="Microsoft.Bcl.HashCode" Version="1.1.1" />
     <PackageReference Update="Microsoft.NET.Test.Sdk" Version="16.11.0" />
-    <PackageReference Update="Microsoft.SourceLink.GitHub" Version="1.0.0" />
+    <PackageReference Update="Microsoft.SourceLink.GitHub" Version="1.1.1" />
     <PackageReference Update="System.CommandLine" Version="2.0.0-beta1.21308.1" />
     <PackageReference Update="System.Memory" Version="4.5.4" />
     <PackageReference Update="xunit" Version="2.4.1" />

README.md

@@ -194,6 +194,7 @@ Options:
   generate-tests-xunit                   Basic tests validating size, blittability, and associated metadata should be generated for XUnit.
   generate-aggressive-inlining           [MethodImpl(MethodImplOptions.AggressiveInlining)] should be added to generated helper functions.
   generate-cpp-attributes                [CppAttributeList("")] should be generated to document the encountered C++ attributes.
+  generate-doc-includes                  <include> xml documentation tags should be generated for declarations.
   generate-file-scoped-namespaces        Namespaces should be scoped to the file to reduce nesting.
   generate-helper-types                  Code files should be generated for various helper attributes and declared transparent structs.
   generate-macro-bindings                Bindings for macro-definitions should be generated. This currently only works with value like macros and not function-like ones.

sources/ClangSharp.PInvokeGenerator/Abstractions/FieldDesc.cs

@@ -10,6 +10,7 @@ internal struct FieldDesc
         public AccessSpecifier AccessSpecifier { get; set; }
         public string NativeTypeName { get; set; }
         public string EscapedName { get; set; }
+        public string ParentName { get; set; }
         public int? Offset { get; set; }
         public bool NeedsNewKeyword { get; set; }
         public bool HasBody { get; set; }

sources/ClangSharp.PInvokeGenerator/Abstractions/FunctionOrDelegateDesc.cs

@@ -12,13 +12,15 @@ internal struct FunctionOrDelegateDesc
         public string NativeTypeName { get; set; }
         public string EscapedName { get; set; }
         public string EntryPoint { get; set; }
+        public string ParentName { get; set; }
         public string LibraryPath { get; set; }
         public string ReturnType { get; set; }
         public CallingConvention CallingConvention { get; set; }
         public FunctionOrDelegateFlags Flags { get; set; }
         public long? VtblIndex { get; set; }
         public CXSourceLocation? Location { get; set; }
         public bool HasBody { get; set; }
+        public bool IsInherited { get; set; }
 
         public bool IsVirtual
         {

sources/ClangSharp.PInvokeGenerator/Abstractions/ValueDesc.cs

@@ -11,6 +11,8 @@ internal struct ValueDesc
         public string TypeName { get; set; }
         public string EscapedName { get; set; }
         public string NativeTypeName { get; set; }
+
+        public string ParentName { get; set; }
         public ValueKind Kind { get; set; }
         public ValueFlags Flags { get; set; }
         public CXSourceLocation? Location { get; set; }

sources/ClangSharp.PInvokeGenerator/CSharp/CSharpOutputBuilder.VisitDecl.cs

@@ -31,6 +31,17 @@ public void EndUnchecked()
 
         public void BeginValue(in ValueDesc desc)
         {
+            if (_config.GenerateDocIncludes && (desc.Kind == ValueKind.Enumerator))
+            {
+                WriteIndented("/// <include file='");
+                Write(desc.ParentName);
+                Write(".xml' path='doc/member[@name=\"");
+                Write(desc.ParentName);
+                Write('.');
+                Write(desc.EscapedName);
+                WriteLine("\"]/*' />");
+            }
+
             if (desc.NativeTypeName is not null)
             {
                 AddNativeTypeNameAttribute(desc.NativeTypeName);
@@ -174,6 +185,11 @@ public void EndValue(in ValueDesc desc)
                 case ValueKind.Enumerator:
                 {
                     WriteLine(',');
+
+                    if (_config.GenerateDocIncludes)
+                    {
+                        NeedsNewline = true;
+                    }
                     break;
                 }
 
@@ -204,6 +220,15 @@ public void EndValue(in ValueDesc desc)
 
         public void BeginEnum(in EnumDesc desc)
         {
+            if (_config.GenerateDocIncludes)
+            {
+                WriteIndented("/// <include file='");
+                Write(desc.EscapedName);
+                Write(".xml' path='doc/member[@name=\"");
+                Write(desc.EscapedName);
+                WriteLine("\"]/*' />");
+            }
+
             if (desc.NativeType is not null)
             {
                 AddNativeTypeNameAttribute(desc.NativeType);
@@ -234,6 +259,17 @@ public void BeginEnum(in EnumDesc desc)
 
         public void BeginField(in FieldDesc desc)
         {
+            if (_config.GenerateDocIncludes && !string.IsNullOrWhiteSpace(desc.ParentName))
+            {
+                WriteIndented("/// <include file='");
+                Write(desc.ParentName);
+                Write(".xml' path='doc/member[@name=\"");
+                Write(desc.ParentName);
+                Write('.');
+                Write(desc.EscapedName);
+                WriteLine("\"]/*' />");
+            }
+
             if (desc.Offset is not null)
             {
                 WriteIndentedLine($"[FieldOffset({desc.Offset})]");
@@ -299,6 +335,28 @@ public void EndField(in FieldDesc desc)
 
         public void BeginFunctionOrDelegate(in FunctionOrDelegateDesc desc, ref bool isMethodClassUnsafe)
         {
+            if (_config.GenerateDocIncludes && !string.IsNullOrEmpty(desc.ParentName))
+            {
+                if (desc.IsInherited)
+                {
+                    WriteIndented("/// <inheritdoc cref=\"");
+                    Write(desc.ParentName);
+                    Write('.');
+                    Write(desc.EscapedName);
+                    WriteLine("\" />");
+                }
+                else
+                {
+                    WriteIndented("/// <include file='");
+                    Write(desc.ParentName);
+                    Write(".xml' path='doc/member[@name=\"");
+                    Write(desc.ParentName);
+                    Write('.');
+                    Write(desc.EscapedName);
+                    WriteLine("\"]/*' />");
+                }
+            }
+
             if (desc.IsVirtual)
             {
                 Debug.Assert(!desc.HasFnPtrCodeGen);
@@ -599,6 +657,15 @@ public void EndFunctionOrDelegate(in FunctionOrDelegateDesc desc)
 
         public void BeginStruct(in StructDesc desc)
         {
+            if (_config.GenerateDocIncludes)
+            {
+                WriteIndented("/// <include file='");
+                Write(desc.EscapedName);
+                Write(".xml' path='doc/member[@name=\"");
+                Write(desc.EscapedName);
+                WriteLine("\"]/*' />");
+            }
+
             if (desc.LayoutAttribute is not null)
             {
                 AddUsingDirective("System.Runtime.InteropServices");
@@ -687,7 +754,20 @@ public void BeginMarkerInterface(string[] baseTypeNames)
 
         public void BeginExplicitVtbl()
         {
-            WriteIndentedLine("public partial struct Vtbl");
+            WriteIndented("public partial struct Vtbl");
+
+            if (_config.GenerateMarkerInterfaces && !_config.ExcludeFnptrCodegen)
+            {
+                WriteLine("<TSelf>");
+                IncreaseIndentation();
+                WriteIndentedLine("where TSelf : unmanaged, Interface");
+                DecreaseIndentation();
+            }
+            else
+            {
+                WriteNewline();
+            }
+
             WriteBlockStart();
         }