Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

XML documentation generated from docs should not contain docs-relative URLs #9555

Closed
Powerhelmsman opened this issue Dec 11, 2018 — with docs.microsoft.com · 1 comment
Assignees
Labels
doc-bug Problem with the content; needs to be fixed [org][type][category] external Not related to content

Comments

Copy link

Powerhelmsman commented Dec 11, 2018

This issue was created by @svick from MicrosoftDocs/feedback#659

Describe the bug
When looking at the XML documentation for an API that seems to have been generated from .Net API reference, such as netstandard.xml, I can see docs-relative URLs such as ~/docs/standard/base-types/regular-expression-options.md, while I think it should point to the live URL for the article: https://docs.microsoft.com/dotnet/standard/base-types/regular-expression-options.
Specifically, netstandard.xml (from version 2.0.3 of the NETStandard.Library package) contains (reformatted):
<member name="F:System.Text.RegularExpressions.RegexOptions.Singleline">
<summary>
Specifies single-line mode. Changes the meaning of the dot (.) so it matches every
character (instead of every character except \n). For more information, see the
"Single-line Mode" section in the
<see cref="~/docs/standard/base-types/regular-expression-options.md">
Regular Expression Options</see> topic.</summary>
<returns></returns>
</member>
Notice how the <see cref> contains a URL that does not make sense outside of the docs repo.
This content seems to come from this line in dotnet/dotnet-api-docs.
Expected behavior
XML documentation contains links to live versions of linked articles.
Note that while there doesn't seem to be spec-approved way provide HTTP links in XML documentation, ReSharper/Rider seems to accept <a href>, and there is a proposal to adopt <see href>: dotnet/csharplang#1764, which is also used by Sandcastle.
Screenshots
This is how the XML documentation is currently presented in Rider, where the link is not very useful:


Document Details

Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

@mairaw mairaw added 🔍 Under Investigation external Not related to content and removed ⌚ Not Triaged Not triaged labels Apr 3, 2019
@mairaw mairaw self-assigned this Apr 3, 2019
@mairaw mairaw added this to the April 2019 milestone Apr 3, 2019
@mairaw mairaw modified the milestones: April 2019, Backlog May 17, 2019
@mairaw
Copy link
Contributor

mairaw commented May 17, 2019

I've checked what's being produced by our latest IntelliSense builds and the link is no longer there (this has been the behavior of how we render links on IntelliSense):

    <member name="F:System.Text.RegularExpressions.RegexOptions.Singleline">
      <summary>Specifies single-line mode. Changes the meaning of the dot (.) so it matches every character (instead of every character except \n). For more information, see the "Single-line Mode" section in the Regular Expression Options topic.</summary>
    </member>

We'd now need to update the .NET Standard package with the latest version of our IntelliSense files.
@ahsonkhan @safern can you guys help with this?

@tdykstra tdykstra added doc-bug Problem with the content; needs to be fixed [org][type][category] P2 labels Oct 24, 2019
@mairaw mairaw closed this as completed Feb 21, 2020
@mairaw mairaw removed this from the Backlog milestone Feb 21, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc-bug Problem with the content; needs to be fixed [org][type][category] external Not related to content
Projects
None yet
Development

No branches or pull requests

5 participants