docs: qualify APIs by assembly so shared namespaces stop colliding - #66
Merged
Conversation
The previous vendored build defaulted `assemblyLabel` to `auto`, which resolved to `suffix` for a flattened layout, so every namespace here read `LinqToDB (linq2db.Tools)` in the table of contents, the page title and the breadcrumb. This site sets no `assemblyLabel` and never asked for that, and 34 of its 40 namespaces are declared by a single assembly, so the label disambiguated nothing on most of them. Upstream now defaults to showing nothing, so the assembly appears only in the UID and the file name, which is all this site ever needed. `source/docfx.json` needs no option change; its comment is updated to say that the default is what keeps the namespaces reading as themselves. `assemblyLabel: shared`, also new upstream, would not change this site: it compares the namespaces of one `metadata` entry, and every entry here documents one assembly, so the six namespace names that do collide across entries are invisible to it. `suffix` on those entries is the option if the assembly should ever be named. docfx rebuilt from `beda63b23`, the same branch as before with the fix on top. Site rebuilt to confirm: 2389 generated API files and 2407 HTML pages, both unchanged; 0 errors and 68 warnings, the same count as the previous build; no `DuplicateUids`, `UidNotFound` or `Ignore duplicated member`; and no table of contents label or page title contains `(linq2db` any more.
MaceWindu
force-pushed
the
docs/assembly-qualified-uids
branch
from
August 14, 2026 13:12
25fa761 to
6fb19e4
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Replaces the
globalPrefixhack with theassemblyUids/assemblyUidOverrideoptions proposed upstream in dotnet/docfx#11090, and refreshes the vendored docfx build that provides them.Why
linq2db documents 17 assemblies in one docfx project and many of them declare the same namespaces, most of all
LinqToDB. A docfx UID is derived from the fully qualified name of an API alone, so those APIs collide: pages overwrite each other,DuplicateUidsis reported, and links to a shared namespace resolve to whichever assembly happened to win. See dotnet/docfx#8966.What changed
source/docfx.jsonnow uses:assemblyUids— the assemblies whose APIs carry the assembly they are declared in as a component of their UID, as inlinq2db.Tools::LinqToDB.Tools.Activity.ActivityStatistics. It is a project level setting because every metadata entry has to agree: an entry mints UIDs for the APIs it references as well as the ones it documents, and a reference that comes out unqualified loses its link with no warning. So every assembly appearing in another assembly's public signatures is listed, not only the ones whose namespaces collide.assemblyUidOverride— the component for the assemblies one entry documents. The four Entity Framework Core entries all build an assembly namedlinq2db.EntityFrameworkCore, so they cannot be told apart by assembly name, and this is the only thing that separates them.The assembly is part of the identity, not of the namespace:
LinqToDBstill reads asLinqToDBin titles, breadcrumbs and links, and only the UID and the file name carry it (::becomes--in file names, as:is not legal there).assemblyLabelis left at its default, which shows nothing — the last commit here is the refresh that fixed an upstream default which had been appending(linq2db.Tools)to every namespace label and page title.LinqToDB.Identityis deliberately absent fromassemblyUids: its namespace does not collide and nothing else here references it.Result
InvalidBookmark(dead in-page anchors)Ignore duplicated memberInvalidAssemblyReferenceDuplicateUids/UidNotFound2389 generated API files, 2407 HTML pages. Of the 68 remaining warnings, 61 are MSBuild noise from the projects themselves (duplicate source files, one analyzer load failure) and the rest predate this work: 5
InvalidFileLinkfrom Microsoft Learn relative links inside linq2db's own XML comments, and 1InvalidBookmarkfrom a hand written#remarksanchor.docfx/README.mddocuments how the vendored build is produced and how to trace it back to its source commit, and notes that this folder goes away once these options ship in a released docfx — thesource/docfx.jsonoptions themselves will not need to change.