[Feature Request] <list type="definition"> support

[paulushub]

The definition list type is not a .NET standard, but widely supported since NDoc days, and I was actually surprised it was not working in DocFX. The content is listed here for reference:

<list type="bullet" | "number" | "table" | "definition">
   <listheader>
      <term>term</term>
      <description>description</description>
   </listheader>
   <item>
      <term>term</term>
      <description>description</description>
   </item>
</list>

For the following documentation:

/// <summary>
/// Gets the numeric identifier of this code list.
/// </summary>
/// <value>A numerical value representing an <c>ISO</c> identifier of the code list.</value>
/// <remarks>
/// <para>
/// By design, the ordinals are specified as follows:
/// </para>
/// <list type="definition">
/// <item>
/// <term>Ordinal = 0</term>
/// <description>Represents an undefined or empty enumeration.</description>
/// </item>
/// <item>
/// <term>Ordinal >= 1</term>
/// <description>Represent the <c>ISO</c> defined enumerations of the code list.</description>
/// </item>
/// </list>
/// </remarks>
public ushort Ordinal { get; }

The definition output is empty:

[filzrev]

It seems <list type="definition"> comments are dropped at XSL transformation steps.

• XmlCommentTransformer.Transform
• XmlCommentTransform.xsl

I thought it can add support <list type="definition"> comments by modifying above XSL template.

[paulushub]

A real work is needed in this tool, and it is really surprising after several years. Even reference code listing is still not working well. Just a simple sample like this:

/// <code lang="cs">
/// [CodeList(&quot;TC_TemplateCode&quot;, &quot;ISO XXXX&quot;)]
/// public sealed class TemplateCode : CodeList&lt;TemplateCode&gt;
/// {
///     public static readonly TemplateCode Empty = new();
/// 
///     public static readonly TemplateCode Mandatory = new(nameof(Mandatory), &quot;mandatory&quot;);
///     public static readonly TemplateCode Optional = new(nameof(Optional), &quot;optional&quot;);
/// 
///     private TemplateCode()
///     {
///     }
/// 
///     private TemplateCode(string name, string identifier)
///         : base(name, identifier)
///     {
///     }
/// }
/// </code>

And Docfx is clearly failing:

I thought I was doing something wrong until, I went back to Sandcastle and found the code listing is working correctly as expected:

[paulushub]

Updates:

1. Wrapping the code listing in <para></para> fixes at least the ending </code></pre> issue.
2. Placing the code listing in <example></example> without any other contents like description, seems to work better.

As it stands now, the docfx is more of markdown documentation tool than the expected .NET reference documentation tool.

[paulushub]

@filzrev, @yufeih Please I wish to look further into the support for reference documentation, I need it. Which implementation will you prefer; fixing the current XSLT process or reimplementing the basic transformation in code? I ask this because the current XSLT only converts to intermediate HTML without applying styling.

[filzrev]

Which implementation will you prefer; fixing the current XSLT process or reimplementing the basic transformation in code?

I've no strong opinions about this.

If it can add support for <list type="definition"> by modifying XSL template. I think that's the simplest solution.

Because Sandcastle specific tags (note) support is already included in existing XSL template. (Thought it's not work on root element) https://github.com/dotnet/docfx/blob/efc1c3df765a3514f2bc5c786e5d05c003a466fd/src/Docfx.Dotnet/Resources/XmlCommentTransform.xsl#L68-L94

Even reference code listing is still not working well.

I've tested provided <code> comment inside <remark> comments. But it's not reproduced on my environment. Is it able to provide reproduceable code?

[paulushub]

Is it able to provide reproduceable code?

It is just a test of concept, nothing special so here you go: ClassLibrary2.zip

[filzrev]

@paulushub Thanks for providing reproduceable source code. I've created separated issue (#10385). And try to create PR to fix reported issue.