dotnet / dotnet/csharplang

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

Open
#8,977 0 comments 0 reactions 1 assignee Claimed by @DustinCampbell View on GitHub
Proposal champion
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.