[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)

docfx/src/Docfx.Dotnet/Resources/XmlCommentTransform.xsl

Lines 68 to 94 in efc1c3d

	<xsl:template match="note">
	<xsl:variable name="type">
	<xsl:choose>
	<xsl:when test="not(normalize-space(@type) = '')">
	<xsl:value-of select="@type"/>
	</xsl:when>
	<xsl:otherwise>note</xsl:otherwise>
	</xsl:choose>
	</xsl:variable>
	<div>
	<xsl:attribute name="class">
	<xsl:choose>
	<xsl:when test="$type = 'tip'">TIP</xsl:when>
	<xsl:when test="$type = 'warning'">WARNING</xsl:when>
	<xsl:when test="$type = 'caution'">CAUTION</xsl:when>
	<xsl:when test="$type = 'important'">IMPORTANT</xsl:when>
	<xsl:otherwise>NOTE</xsl:otherwise>
	</xsl:choose>
	</xsl:attribute>
	<h5>
	<xsl:value-of select="$type"/>
	</h5>
	<p>
	<xsl:apply-templates select="node()"/>
	</p>
	</div>
	</xsl:template>

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.