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

[DustinCampbell]

• Discussion: Proposal: allow 'href' attributes (particularly in <see> and <seealso> elements) #8978

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:

• Adding documentation about the rest of the classes involved on generating the CSharpAPI machinelearning#529 (comment)
• 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:

  <see href="https://github.com/dotnet/csharplang/"/>
  <see href="https://github.com/dotnet/csharplang/">The official repo for the design of the C# programming language</see>

• 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.