dotnet / dotnet/csharplang

[Proposal]: allow 'href' attributes (particularly in <see> and <seealso> elements)

Open
#8,979 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/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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.