[Proposal]: allow 'href' attributes (particularly in <see> and <seealso> elements)
- 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/8978
## Summary
[summary]: #summary
### Motivation
Currently, the C# language does not provide clear facilities for referencing external content addressable by a URI. This leads to confusion among developers regarding the best plan to include such content in documentation:
* https://github.com/dotnet/machinelearning/pull/529#discussion_r202773275
* https://stackoverflow.com/questions/6960426/c-sharp-xml-documentation-website-link
### Detailed design
This proposal involves three components, each of which should be formalized for inclusion in the language specification.
* The `href` attribute of documentation comment elements is defined, with the value as a URI. The compiler MAY report a warning if the value is not a valid URI.
* The `see` and `seealso` elements are updated to allow for the use of `href` attribute. The compiler MAY report a warning if both the `cref` and `href` attributes are used for the same reference. The following shows examples of how this may appear:
```xml
The official repo for the design of the C# programming language
```
* The `see` and `seealso` elements are updated to indicate the content of the element, if provided, should be used as the display text of the reference.
This change is likely to not require any core changes in the behavior of the compiler. However, tools (including the IDE component of dotnet/roslyn) are likely to require updates to ensure correct presentation of these references.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.