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.

[EWSoftware]

Can you attach an example demonstrating the issue?

[Zastai]

I think this may be the same issue as #1057 - we use CPVM too, and I probably will not have used it when I tried to make the minimal reproduction case for #1052.

[Zastai]

Thanks to #1057 I now have a reproduction test case.

1. Extract the zip file
2. Build the solution by whatever means
3. Build the doc project (using dotnet build, not msbuild.exe); this should work without any errors
4. Open the generated documentation and not that the Inherited class is missing, and so are the Method1 and Method2 methods on SomeClass

Editing lib.csproj, uncommenting the marked property, and rebuilding the solution makes things work.

issue-1051-1052.zip

[EWSoftware]

This appears to be related to central package management. I was able to duplicate this issue and #1052 with dotnet build and MSBuild. Using the standalone GUI with your test project worked. Once I modified your test project to use my local copy with the fix rather than the SHFB NuGet package it worked as expected. So, this issue and #1052 should be resolved once I publish the new release.