[Proposal]: do not require <description> in <list> without <term>

[DustinCampbell]

• Discussion: Proposal: do not require <description> in <list> without <term> #8976

Summary

Motivation

Currently, the C# language specification describes the <item> documentation element as always requiring the child element <description>. This includes cases like numbered and bulleted lists where the <term> element is omitted. In these cases, the <description> element is unnecessarily verbose and the compiler does not provide an assistance in creating conforming documentation comments.

dotnet/machinelearning#529 (comment)
dotnet/roslyn#29018

Detailed design

The C# language specification is updated as follows (final wording TBD):

If an <item> element within a <list> element is missing both the <term> and <description> elements, the inner XML of the <item> element is treated as the inner XML of an implicit <description> element.

In other words, the following become equivalent:

<list type="number">
  <item><description>Text of the item</description></item>
</list>

<list type="number">
  <item>Text of the item</item>
</list>

Remarks

This behavior aligns with both user expectations and the long-standing behavior of Sandcastle Help File Builder. This behavior also aligns with the current C# compiler behavior and the IDE experience, so implementation of the proposal will be limited to a change in the wording of the language specification to allow this case.

/cc @EWSoftware @BillWagner @sfilipi