Triple slash comment 'item' tag generates an empty list item

[martinivanoff]

The following C# XML comment generates a list with two empty list items.

XML:

///<list type="bullet"> /// <item>Item 1</item> /// <item>Item 2</item> ///</list>

Generated YAML:

remarks: "\n<ul><li></li><li></li></ul>\n"

[vwxyzh]

See: https://docs.microsoft.com/en-us/dotnet/csharp/codedoc#list

Source code: https://github.com/dotnet/docfx/blob/dev/src/Microsoft.DocAsCode.Metadata.ManagedReference.Common/Transform/TripleSlashCommentTransform.xsl#L188

[KalleOlaviNiemitalo]

list in Sandcastle XML Comments Guide says that, for list/@type="bullet" and list/@type="number", the inner text of the item element is rendered if the term and description child elements are omitted. "Area-SandcastleParity" might be appropriate.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in a week if no further activity occurs.

[stale[bot]]

Closing this issue after a prolonged period of inactivity. If you still think this issue is relevant, please feel free to ping a maintainer or leave a comment.

[craigfowler]

It is not only Sandcastle which behaves in this way. VS Code for example (with Omnisharp) will render list contents as described in this issue. Here's a screenshot of a tool-tip from an editor.

I hadn't even realised that the <term> and <description> tags existed. I've been using bare <item> for so long (and supported by every tool I'd used) that I was unaware that technically I was doing anything wrong. So, I'd support including this feature based on the principle of least astonishment.

For now, though (now I know) I'm happy with the workaround that I must use term and/or description tags.

[eli-darkly]

I was also blindsided by this behavior, and will now have to edit the docs in quite a few projects to add <description> tags. I do see that in the current .NET language reference pages (as opposed to the Sandcastle docs), <item> is described as always requiring a <description>— so it may be that this was always a non-canonical behavior of Sandcastle. If so, that's unfortunate, since <item><description> is an extremely verbose way to write a bullet list item.

[TermWay]

If Visual Studio support this, I think it's fair to say that docfx should also support it.

[dotMorten]

Nice to see a PR has been submitted to address this. It's been quite an issue for us.