dotnet / dotnet/docfx

Cross-reference silently ignored

Open
#5,670 10 comments 0 reactions 0 assignees View on GitHub
dotnet: xml-comment xref
Dominant language
C#
Stars
4.4k
Forks
890
Avg merge
2h 9m
Merged PRs (30d)
11

Description

**Operation System**: `Windows`

**DocFX Version Used**: 2.51.0 (NuGet)

**Template used**: `default`

**Steps to Reproduce**:

1. Unzip the attached minimal repro : [docfx-bug.zip](https://github.com/dotnet/docfx/files/4381887/docfx-bug.zip)
2. Run docfx with `docfx.exe --intermediateFolder .\obj -o .\build --serve --debug`
3. Observe the warning `Invalid cref value "!:A.B.BaseClass.Field" found in triple-slash-comments for OtherClass, ignored`
4. Open http://localhost:8080/api/A.B.C.html and observe the "See: ." missing the reference to `A.B.BaseClass.Field`.

So far so good, even though I am not sure why `cref` doesn't work here. Anyway, on to the actual bug:

5. Change `other.cs` and replace `cref` with `xref`
6. Run docfx again (same args)
7. Observe no warning
8. Open http://localhost:8080/api/A.B.C.html and observe again the "See: ." missing the reference to `A.B.BaseClass.Field`.

**Expected Behavior**:

- Either a warning about an invalid reference (although I don't see why... but I am not an xref expert)
- Or actually the cross-reference generating a text with a link (hyperlink)

**Actual Behavior**:

Cross-reference XML tag is copied as-is to the output, and not rendered by the browser which cannot understand _e.g._ `` tags.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.