You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Replaces the ad-hoc FileNameSanitizer with a shared symbol-name registry so every generated file name is predictable, legal, and collision-free across .NET, C++ and VHDL. Follow-up to #58, which deferred the collision findings (Copilot review threads, including the high-severity A.B namespace vs. type collision).
How it works
Every symbol that needs a file is registered (no filename assigned yet).
Every name is resolved once, up front, with no collisions (case-insensitive).
Writers and link resolvers only read the approved map. Names are escaped exactly once.
Predictable names come first ("primary name wins"); a -N suffix (starting at -2) is used only as a last resort. The complete numbered rules (NR-01..NR-20) are in docs/design/api-mark-core/file-naming-rules.md.
Highlights:
Namespaces are registered: namespace A { class B } vs namespace A.B -> namespace keeps A/B.md, the type becomes A/B-2.md; children move with the displaced parent.
Generic types use brace arity: Foo{1}, Foo{2} (was Foo-1).
Explicit interface members keep type arguments: IFoo{int}.Get, IPair{int-string}.Get.
Reserved pages (api, operators), Windows device names, case twins, and VHDL entity/package twins (Api/API) are all handled.
Illegal characters become _; invisible symbols are registered so names are stable across visibility settings.
FileMarkdownWriterFactory rejects illegal segments; LinkPath builds/escapes link destinations.
Breaking change
Generated file names change (Foo-1.md -> Foo{1}.md, case twins get separate pages, etc.). No legacy mode: output is regenerated each build and shipped with the package, so only link integrity matters (brief note in build notes).
Testing
New Core tests (registry, rules, link paths), per-language naming tests, and a DotNet synthetic-assembly suite with exact-name assertions.
Property-style tests: all paths unique (case-insensitive) and legal across large fixtures at all visibilities; every link resolves to a real file.
Local: Core 242, DotNet 852 (net8/9/10), VHDL 101, Tool 132, MSBuild 68 pass. C++ clang tests and the vcxproj package test can't run locally (no clang); CI covers them.
Reviews
Code review: no findings. Formal reviews of all affected review-sets: PASS (after fixing uncovered files, IsLegalSegment/LinkPath.Escape vs NR-06/NR-19, and empty-key handling). lint.ps1 clean; reqstream --enforce has no orphans.
Known limits
Links to types in another mapped assembly use that type's predictable name (wrong only if that package displaced it with -N).
Brace/percent-encoded link destinations haven't been spot-checked on a live Markdown renderer.
Single source of truth for generated file names: register all symbols,
resolve names once with tiered precedence and a last-resort -N suffix,
then read approved names.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…gistry
Namespaces, types, nested types, members and operators pages are registered
up front for the whole module (independent of visibility) and resolved once.
Generic types use brace arity (Foo{1}); explicit interface members keep type
arguments; case twins get separate pages; links read the approved names.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Update the api.md naming appendix and wording in test comments.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The updated naming description removes the case-collision combined page, but the next bullets still document a Combined page keyed by a lower-cased member name. The .NET emitter now gives case twins separate registry-approved pages; this section should describe the overload page instead so the design document does not specify a page that is no longer emitted.
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
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.
Summary
Replaces the ad-hoc
FileNameSanitizerwith a shared symbol-name registry so every generated file name is predictable, legal, and collision-free across .NET, C++ and VHDL. Follow-up to #58, which deferred the collision findings (Copilot review threads, including the high-severityA.Bnamespace vs. type collision).How it works
Predictable names come first ("primary name wins"); a
-Nsuffix (starting at-2) is used only as a last resort. The complete numbered rules (NR-01..NR-20) are indocs/design/api-mark-core/file-naming-rules.md.Highlights:
namespace A { class B }vsnamespace A.B-> namespace keepsA/B.md, the type becomesA/B-2.md; children move with the displaced parent.Foo{1},Foo{2}(wasFoo-1).IFoo{int}.Get,IPair{int-string}.Get.api,operators), Windows device names, case twins, and VHDL entity/package twins (Api/API) are all handled._; invisible symbols are registered so names are stable across visibility settings.FileMarkdownWriterFactoryrejects illegal segments;LinkPathbuilds/escapes link destinations.Breaking change
Generated file names change (
Foo-1.md->Foo{1}.md, case twins get separate pages, etc.). No legacy mode: output is regenerated each build and shipped with the package, so only link integrity matters (brief note in build notes).Testing
Reviews
Code review: no findings. Formal reviews of all affected review-sets: PASS (after fixing uncovered files,
IsLegalSegment/LinkPath.Escapevs NR-06/NR-19, and empty-key handling).lint.ps1clean;reqstream --enforcehas no orphans.Known limits
-N).