Skip to content

triple-slash links to .NET base libraries erase output #7245

@Emdot

Description

@Emdot

Operating System: Windows

DocFX Version Used: 2.56.7.0

Template used: default

Steps to Reproduce

Here's a minimal repro: docfx-issue.zip

  1. In C# code, add /// comments that reference a BCL class, such as System.Exception.
  2. Add all relevant using lines.
  3. In docfx.json, set xrefService to https://xref.docs.microsoft.com/query?uid={uid}
  4. Run docfx

Expected Behavior

Ideally, docfx should use the xrefService to make a link. At minimum, though, it should show the original text.

Actual Behavior

docfx fails to resolve the links, and the text does not appear.

Details

The C# from the repro:

using System;
using System.Threading.Tasks;
namespace Testing
{
	public class Class1 
	{ 
		/// <summary>
		/// Cref: <see cref="System.Threading.Tasks.Task"/>
		/// <br/>
		/// Xref: @System.Threading.Tasks.Task
		/// </summary>
		/// <exception cref="System.Exception">exception doc</exception>
		public void Foo()
		{
		}
	}
}

In the output, note that:

  • The xref resolved correctly, which shows that docfx can resolve the reference and that xrefService is configured correctly.
  • For the cref, the text is missing. At minimum, it should say System.Threading.Tasks.Task even if it's not a link.
  • The exception documentation is missing entirely.
    2021-03-29 21_12_31-Class Class1

These are the warnings:

[21-03-30 02:09:08.783]Warning:[MetadataCommand.ExtractMetadata]Invalid cref value "!:System.Threading.Tasks.Task" found in triple-slash-comments for Foo defined in C:\Users\3mave\source\tests\docfx-issue\src\Class1.cs Line 12, ignored.
[21-03-30 02:09:08.786]Warning:[MetadataCommand.ExtractMetadata]Invalid cref value "!:System.Exception" found in triple-slash-comments for Foo defined in C:\Users\3mave\source\tests\docfx-issue\src\Class1.cs Line 12, ignored.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions