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

[sharwell]

Champion issue: #8979

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.

[alrz]

I wish we could invest in markdown doc comments instead. XML is not a great format for in-code documentation.

[artus]

I saw someone writing their documentation in yaml instead of xml, which is also a bit more human-readable than xml.

[michael-hawker]

@sharwell this has been open for a while and is labeled blocked, what is it blocked on?

[sharwell]

@michael-hawker IIRC, the language team concluded they are more interested in reviewing a complete proposal that addresses many outstanding usability issues related to documentation comments, as opposed to trying to review a bunch of small changes.

[michael-hawker]

@sharwell isn't this more of a bug than a proposal since other well-known tools in the xmldoc ecosystem support have supported this syntax for a while now?

Like DocFX: https://dotnet.github.io/docfx/api/Microsoft.DocAsCode.DataContracts.ManagedReference.LinkType.html
And Sandcastle: https://ewsoftware.github.io/XMLCommentsGuide/html/983fed56-321c-4daf-af16-e3169b28ffcd.htm

It's also called out in our docs here: https://docs.microsoft.com/dotnet/csharp/programming-guide/xmldoc/see

It also seems to be supported in Roslyn: https://github.com/dotnet/roslyn/blob/main/src/Features/Core/Portable/DocumentationComments/AbstractDocumentationCommentFormattingService.cs#L324-L345

So I'm even more confused about what's what.

[KalleOlaviNiemitalo]

see/@href, see/@langword, and seealso/@href were added to the C# 6 standard draft in dotnet/csharpstandard@ffa424a.

[KalleOlaviNiemitalo]

This change is included in ECMA-334 6th edition June 2022 and ECMA-334 7th edition December 2023.

[KalleOlaviNiemitalo]

This part of the proposal however has not been done:

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.

In ECMA-334, the see and seealso elements do not have content: neither in the syntax specification nor in the examples.

If ECMA-334 were changed to say that these elements may have content to be used as display text, then I think it should also say that, if the element has no content, then the display text should be generated by the documentation viewer and not by the documentation generator.

[ZacharyPatten]

For projects with API documentation such as projects using docfx it would be nice if there was a standardized way to link to the documentation of a code member from the XML. I opened this discussion on docfx: dotnet/docfx#7458
However I recommended a tool that automatically adds the link to the <summary> node, because that seems like the only real place we have at the moment.

I wish there was a standard xml node like <link> that would be recognized by Roslyn, so we don't have to tack it on the end of <summary>.