Add support for Xml code documentation exported to header

[climblinne]

When a xml documentation file is found parallel to the assembly, this is used to produce code documentation in the C header file.

So just add your XML comments to the function:

/// <summary>
/// Test documentation
/// </summary>
/// <param name="pString">Pointer to string</param>
/// <returns></returns>
[UnmanagedCallersOnly(EntryPoint = "my_ReleaseString")]
[return: DNNE.C99Type("MyStatusCode")]
public static int ReleaseString([DNNE.C99Type("const char**")] System.IntPtr pString)

Enable "XML documentation file" with same file name as assembly with xml extension. At the moment the path must be set to the intermediate directory (e.g. obj\Debug\net5.0\ExportingAssembly.xml)

And the generated header will produce the following C header

// Computed from MyWrapper.MyExports.ReleaseString
/// <summary>
/// Test documentation
/// </summary>
/// <param name="pString">Pointer to string</param>
/// <returns></returns>
DNNE_EXTERN_C DNNE_API MyStatusCode DNNE_CALLTYPE my_ReleaseString(const char** pString);

[climblinne]

@AaronRobinsonMSFT So I still got one problem. Maybe you can help out there. I see in the DNNE-targets the usage of the IntermediateAssembly. The problem with this path is, that there is no documentation file at the same location. This is normally only in the root and the output path. I changed the XML documentation file to obj\Debug\net5.0\ExportingAssembly.xml and then it works. I could also generate an third parameter for the XML documentation file in dnne-gen, but I have no idea, how to transfer this into the DNNE-targets.

[climblinne]

Now only a good hint, how to integrate it into DNNE-targets is missing...

[AaronRobinsonMSFT]

Now only a good hint, how to integrate it into DNNE-targets is missing...

I would update the following to provide a path to the xml file. This way we could pass something akin to -d $(XmlDocFile). I would do the existence checking in MSBuild and then dnne-gen can just consume the supplied doc file as needed.

https://github.com/AaronRobinsonMSFT/DNNE/blob/385ea4aafc7ed81a46a0c1209ff7f12e8578ac93/src/msbuild/DNNE.targets#L72

Flag parsing in dnne-gen.

https://github.com/AaronRobinsonMSFT/DNNE/blob/385ea4aafc7ed81a46a0c1209ff7f12e8578ac93/src/dnne-gen/Program.cs#L110-L140

[climblinne]

@AaronRobinsonMSFT So I added the command line option, this was the easy part. Put how to put the variable through the "TARGETS"?

[AaronRobinsonMSFT]

@AaronRobinsonMSFT So I added the command line option, this was the easy part. Put how to put the variable through the "TARGETS"?

This is relatively easy but does require working with MSBuild. The first thing is to determine how the project system computes the documentation file and then pass that to the command line. Using a binlog would be informative here as it will help you understand where property are set and what values exist during compilation - pass /bl as an argument to dotnet build.

[AaronRobinsonMSFT]

@climblinne My quick investigation yields that the property containing the name of the file is $(DocumentationFile). A quick guess at what would be needed to enable this is something like below. The built-in MSBuild condition functions can be found here.

<PropertyGroup>
  <DocFlag Condition="Exists($(DocumentationFile))">-d &quot;$(DocumentationFile)&quot;</DocFlag>
</PropertyGroup>

<Exec Command="$(DnneGenExe) @(IntermediateAssembly) $(DocFlag) -o @(DnneGeneratedSourceFile)" />

[climblinne]

Thanks for the help. I think, from my side it's working now. Just enable "GenerateDocumentationFile" in the project settings and add some xml documentation to the export function.

[AaronRobinsonMSFT]

@climblinne This looks great. I pulled it down and it works as expected for me too. Two final bookkeeping asks.

1) Add an entry to the FAQs about how to get documentation pushed into the header file. 2) Update ExportingAssembly.csproj with the following properties so we can have some testing of the process.

    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <!-- Disable warnings about missing comments -->
    <NoWarn>1591</NoWarn>

[AaronRobinsonMSFT]

@climblinne Thank you! I will publish a new package in a few days.

[AaronRobinsonMSFT]

@climblinne A new package with this support has been published https://www.nuget.org/packages/DNNE/1.0.31. Thank you for the contribution.