Making SharpGenTools Document Your Mappings

SharpGenTools gives you two options for how to automatically document your mappings.

External Documentation Comments

You can supply external documentation though XML files structured as below:

<comments>
    <comment id="C++ or C# Element Name">
        <summary>Summary here</summary>
    </comment>
</comments>

SharpGenTools will automatically include an <include> documentation tag that points to a matching element in an external documentation file. You can specify an external comments file to SharpGen by adding it as a SharpGenExternalDocs item in your project file.

Doc Providers

Sometimes you’re mapping an already documented library, and you don’t want to have to manually extract the documentation for each element you’re documenting. SharpGen provides the IDocProvider interface that you can extend:

#nullable enable

using System.Threading.Tasks;

namespace SharpGen.Doc;

/// <summary>
/// An <see cref="IDocProvider"/> implementation is responsible to provide documentation to the Parser
/// in order to feed each C++ element with an associated documentation.
/// This is optional.
/// A client of Parser API could provide a documentation provider
/// in an external assembly.
/// </summary>
public interface IDocProvider
{
    /// <summary>
    /// Finds the documentation for a particular C++ item.
    /// </summary>
    /// <param name="fullName">
    /// The full name.
    /// For top level elements (like struct, interfaces, enums, functions), it's the name of the element itself.
    /// For nested elements (like interface methods), the name is of the following format: "IMyInterface::MyMethod".
    /// </param>
    /// <param name="context">Environment for documenting, used to create items and subitems</param>
    /// <returns>Non-null documentation item container created by <see cref="IDocumentationContext"/></returns>
    Task<IFindDocumentationResult> FindDocumentationAsync(string fullName, IDocumentationContext context);

    /// <summary>
    /// If true, any exception thrown, or any error logged by this provider will cause the build to fail.
    /// </summary>
    /// <remarks>
    /// For providers that rely on unstable factors (networking), it is recommended to set this to <c>false</c>.
    /// However, the default choice should be <c>true</c>.
    /// </remarks>
    bool TreatFailuresAsErrors { get; }

    /// <summary>
    /// Name of the documentation provider to be presented to user when needed.
    /// </summary>
    /// <remarks>
    /// Short version. Without words like "documentation provider" or "extension".
    /// </remarks>
    string UserFriendlyName { get; }
}

You can reference the SharpGen package on NuGet to get a reference to the assembly. To enable installed doc providers, set the $(SharpGenGenerateDoc) property to true. By default, SharpGenTools.Sdk does not ship with any doc providers.

Doc Providers MSBuild Integration

To integrate into MSBuild, you need to create an MSBuild task. The MSDN Doc Provider task project in the SharpGen.Doc.Msdn repository (SharpGen.Doc.Msdn.Tasks), is a great example of how to create your own doc provider and hook it into the build process. If you are going to publicly publish the doc provider task, please make the task share the same condition statement as the one in SharpGen.Doc.Msdn.Tasks so users can easily enable the provider in a standard way.