Missing references with interface implementation

[jskeet]

Operation System: (Windows or Linux or MacOS)

Windows

DocFX Version Used:

2.47

Template used: (default or statictoc or contain custom template)

Irrelevant

Steps to Reproduce:

1. Unzip the attached sample
2. Run builddocs.sh (or run the steps manually)

Expected Behavior:

The documentation for Library1.Foo should be able to refer to the documentation for Library2.IFoo, given the xref map reference in Library1/docfx.json

Actual Behavior:

The xref map appears to be loaded, but the external reference can't be found:

[19-11-06 09:37:12.506]Info:[BuildCore.Build Document.LinkPhaseHandlerWithIncremental.UpdateContext]0 external references found in 2 xref maps.

(This is then visible in the generated docs - I'd expect a link, but it's just shown as Library2.IFoo in the docs.)

This may well have the same cause as #4792.

Docfx becomes significantly less useful for multi-library documentation when cross references can't be resolved. I may try to work out how to debug docfx myself to investigate further, given the lack of attention to the possibly-related bug. MissingReferences2.zip

[jskeet]

After debugging into this a little bit, I suspect there's an ordering problem here. By the time the DocumentBuilderContext gets to the stage where it would load references from the xref maps, the UIDs in question are already in ExternalXRefSpec, but without hrefs. This is from LinkPhaseHandler.HandleSaveResult, which appears to register "external" specs even though they haven't been loaded from an external source.

At that point I'm frankly lost as to what's meant to do what, but hopefully this helps a little for someone else doing the digging.

[jskeet]

Ping? It would be nice to get some response here with an idea of whether anything is likely to happen.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in a week if no further activity occurs.

[jskeet]

Ping to avoid closing. This is an important issue IMO, and I'm a little disappointed it hasn't gained any traction.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in a week if no further activity occurs.

[jskeet]

Another ping on this? (Apparently the stale bot hasn't actually closed it...) It would be really nice to get some input from the maintainers on this - it's a pretty important issue IMO.

[schwjm]

I am experiencing the same issue. Searching around GitHub a bit, I also found at least one other DocFX consumer that was relying on this but getting nothing from their external xref map either.

xrefService appears to work just fine (e.g. System references resolve from the typical "xrefService": [ "https://xref.docs.microsoft.com/query?uid={uid}" ]. This suggests a humorous workaround of implementing a temporary web-service that reads a xrefmap.yml and answers queries.

This should not be stale. This is a killer feature!

[jskeet]

I'm currently investigating a very similar situation (again): https://github.com/googleapis/google-cloud-dotnet/issues/6741 - I'd entirely forgotten I'd filed this issue.

My expected workaround is to add isExternal to references in the YAML file. I haven't checked whether that would help in this case.

[schwjm]

@jskeet I'm not sure that's everything, I am dealing two libraries, one with PackageReference to the other. All of my references already have isExternal as apparently expected. Perhaps I'm doing something else wrong on my end, though.

[schwjm]

I'll withdraw my me-too, as I think I was running into some odd caching behaviors that don't quite fit in with this ticket. I'll post something else if I find something solid to report.