CODEWITHSUNDEEP
c#visual-studio-2017docfx
Mike Bruno
Mike Bruno

Reputation: 634

.NET API Documentation with DocFX - How to properly display a method call in a code example

I'm trying to leverage the XML notation feature in Visual Studio in order to build documentation for an API I'm writing. I'm running into a problem where I can't figure out how to reference a method name in my code sample without automatically populating the parameter types

Example:

    /// <summary>
    /// Exports the certificate corresponding to the specified certificate thumbprint to a Base64-encoded text file
    /// </summary>
    /// <param name="certThumbprint">Certificate thumbprint (case-insensitive)</param>
    /// <param name="exportPath">Fully-qualified path to where the Base64-encoded file should be written (a ".cer" file extension will be added if no file extension is detected)</param>
    /// <param name="certStore">(Optional) The certificate store where the encryption certificate resides (Default: <see cref="CertStore"/>.<see cref="CertStore.CurrentUser"/>)</param>
    /// <param name="verbose">True enables verbose logging</param>
    /// <returns>The fully-qualified path to where the Base64-encoded certificate file was ultimately written</returns>
    /// <example>
    /// <code>
    /// string thumbprint = @"ccdc673c40ebb2a433300c0c8a2ba6f443da5688";
    /// string exportPath = @"C:\data\cert";
    /// <see cref="CertStore"/> certStore = <see cref="CertStore"/>.<see cref="CertStore.CurrentUser"/>;
    /// string finalExportPath = <see cref="X509Utils"/>.ExportCert(thumbprint, exportPath, certStore);
    /// //finalExportPath is @"C:\data\cert.cer"
    /// </code>
    /// </example>

This garners the following results using DocX:

Rendered documentation

Why can't I refernce the method name without automatically displaying the parameter types? Do I need to use a string literal for the method call in the example rather than referring to it?

Upvotes: 0

Views: 573

Answers (1)

Mike Bruno
Mike Bruno

Reputation: 634

The content being served was from a cached version of the API documentation. Completely deleting and re-creating the DocFX project resolved the issue. The XML documentation in my example above renders properly.

Upvotes: 1

Related Questions