[Proposal]: do not require <description> in <list> without <term>
- Dominant language
- C#
- Stars
- 12.7k
- Forks
- 1.1k
- Avg merge
- 11h 1m
- Merged PRs (30d)
- 3
Description
* Discussion: https://github.com/dotnet/csharplang/discussions/8976
## Summary
[summary]: #summary
### Motivation
Currently, the C# language specification describes the `` documentation element as always requiring the child element ``. This includes cases like numbered and bulleted lists where the `` element is omitted. In these cases, the `` element is unnecessarily verbose and the compiler does not provide an assistance in creating conforming documentation comments.
https://github.com/dotnet/machinelearning/pull/529#discussion_r202801954
https://github.com/dotnet/roslyn/pull/29018
### Detailed design
The C# language specification is updated as follows (final wording TBD):
> If an `` element within a `` element is missing both the `` and `` elements, the inner XML of the `` element is treated as the inner XML of an implicit `` element.
In other words, the following become equivalent:
```xml
Text of the item
Text of the item
```
### 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
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.