Clarify which BCL types have automatic xref resolution

[glopesdev]

I was really surprised to find out that System.UInt32 does not resolve automatically, whereas System.String, System.Boolean and System.Int32 all resolve without the need for the xrefmap.

Therefore, the below documentation note requires more clarification to help understand exactly which types might require xrefmap resolution:

https://github.com/dotnet/docfx/blob/ec996d50646d2274a981f9deae49ad1b1dd03d5a/docs/docs/links-and-cross-references.md?plain=1#L166

To reproduce, set the below reference style links in any markdown file and note that UInt32 fails to resolve without an explicit reference to the .xrefmap.json file from learn:

[`Boolean`]: xref:System.Boolean
[`String`]: xref:System.String
[`Int32`]: xref:System.UInt32
[`UInt32`]: xref:System.UInt32

[filzrev]

I've tried to reproduce reported issue. But it can't be reproduced on my environment.

Is it able to provide files that can reproduceable reproduce issues.

What's I've tested

1. Run docfx init --yes

2. Edit index.md and add following contents

   - <xref:System.Boolean>
   - <xref:System.String>
   - <xref:System.Int32>
   - <xref:System.UInt32>
   

3. Run docfx build --serve and confirms xref links are not resolved
   (Because BCL libraries xref are resolved when API metadata generation. And not works on conceptual document)
   

4. Add following setting on docfx.json

   "xref": [
     "https://learn.microsoft.com/en-us/dotnet/.xrefmap.json",
   ],
   

5. Run docfx build --serve and confirms all xref links are resolved.

[glopesdev]

I've tried to reproduce reported issue. But it can't be reproduced on my environment.

@filzrev I am not sure I understood whether or not you were able to reproduce the issue, but I did try to upgrade to the latest version of docfx and run through your steps and indeed the references all come up unresolved. Is this expected?

Interestingly, strictly following your steps also resulted in an exception I have never seen before:

DocfxException: Node.js executable is not found. Try to install Node.js or set the `PLAYWRIGHT_NODEJS_PATH` environment variable.

This turns out to come down to having "pdf": true in the default template, which I feel is probably a bad idea, since PDF is not necessarily a common output for doc websites, and especially if it requires something which is not included in the default system install it will create a lot of friction for new DocFX users.

Anyway, I will raise a separate issue about that.

In your case it seems like no BCL reference is resolved at all until the .xrefmap file is included, but strangely that is not what we experience in our builds (the .xrefmap is required for some types, but not others).

I am not entirely sure what is wrong at this point, also because I'm not sure about what is expected. Should docfx resolve any BCL type at all, or is it an accident of a specific project or Roslyn configuration?

In any case, I do feel the main issue I was trying to raise here remains, which is the need to clarify which exact BCL types (if any) are expected to be automatically resolved by docfx.

[filzrev]

I am not entirely sure what is wrong at this point, also because I'm not sure about what is expected. Should docfx resolve any BCL type at all, or is it an accident of a specific project or Roslyn configuration?

Reported behaviors seems be occurred, because some BCL type are referenced on doc comment. And these uids are exposed as API metadata and resolved when conceptual document.

See: https://github.com/dotnet/docfx/issues/9480