Some types excluded from documentation?

[Zastai]

I will try to make a reproducible test case, but we're having an issue where a number of classes are being left out of the documentation output. In addition, it's in heavy use so there are literally thousands of "Unknown reference link target" messages from other types in the same assembly and namespace.

The log shows nothing special; GenerateRefInfo outputs:

         Microsoft.Build (v17.8.5+b5265ef370a651f8c3458110b804e5cbf869eeb5)
         © Microsoft Corporation. All rights reserved.
         No source code context base path specified.  Source context information is unavailable.
         Loaded 1 assemblies for reflection and 167 dependency assemblies.
         Wrote information on 9 namespaces, 384 types, and 3616 members
         Merging duplicate type and member information
         Merged 0 duplicate type(s) and 0 duplicate member(s)

No warnings or errors are shown until GenerateInheritedDocumentation correctly warns about some missing docs (on unrelated types), and then BuildTopics reporting the "Unknown reference link target".

The type I initially noticed this for is a very large one (over 500 method, over 100 of which are operator overloads), so I thought there might be a limitiation at play there. But then I noticed some other much smaller types were similarly affected, so I am at a loss as to any possible cause.

The SHFB project has a single csproj documentation source, so all affected types are from the same assembly, and they are all public. There is an API filter active to hide internal namespaces, but if I remove that, the problem remains (it just adds another ~2000 "unknown reference" messages).

Is there any way of tracing what types were considered for inclusion and why they were included/excluded?

[Zastai]

It does seem to be an issue in the GenerateRefInfo step. If I interrupt the build after it has run and look into the obj folder, I see

• the intellisense file for the assembly being documented
• a GenerateRefInfo-<guid>.proj file
• MRefBuilder.config
• reflection.nofilenames, reflection.org and reflection.xml
• StopWordList.txt

The IntelliSense file has <doc>/<members>/<member name="T:Foo.Bar"> entries for all the affected types, but none of the reflection.xxx files include corresponding <reflection>/<apis>/<api id="T:Foo.Bar"> entries.

[Zastai]

It seems to be connected to the documented project targeting net8.0.

When I added CopyLocalLockFileAssemblies to it (as part of tests for #1052), I noticed that the number of warnings jumped massively (from ~2200 to 6500+.

Looking into it, it turns out that most of those were correct complaints about missing documentation tags, and the types missing from the documentation when building "normally" were now present in the documentation.
The logs are mostly identical; the notable difference is that GenerateRefInfo reports:

Wrote information on 7 namespaces, 381 types, and 5922 members

but the output tree for the run where the source project had CopyLocalLockFileAssemblies set to true had over 4000 more entries under the html folder, showing that the impact of this issue is much larger than it initially seemed based on the SHFB build warnings alone.

That means I now seem to have a workaround, but not an explanation or a solution, for this issue.

What might be happening is that any type that references a type from a package dependency causes an internal error that is neither handled nor reported, causing the silent omissions.