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
{{ message }}
Repository navigation
Fix DotNet output regressions reported against 0.5.8 and add regression tests - #58
Fixes the DotNet output regressions and gaps reported against ApiMark 0.5.8 (found while documenting Plexus), and adds regression tests so each fix is guarded by exact-output assertions.
Reported issues fixed
void? return types in nullable contexts; params modifier; virtual/override/abstract/sealed/new modifiers and a protected marker in overview rows
Inherited members ("Inherited from X" sections, including abstract and external bases)
Overview tables and overload headings keep defaults, reference-type ?, and C# tuple syntax
Overload index rows list distinct return types and a shared/neutral summary; generic overload examples stay under their own heading
Generic types: Foo<T> page titles, Type Parameters tables (types and methods), constraints
Private/internal setters no longer rendered
External <inheritdoc/> resolved from reference XML or treated as documented
Record primary constructor descriptions
Navigation: API Reference breadcrumb on every page, "Start here" and Key Types in api.md
External Types table uses C# names and escapes generics
Cross-package links: ApiMarkLinkVersion > PackageVersion > Version precedence with a mismatch warning; prose <see cref> and nested-type crefs link
<paramref>, <typeparamref> and <see langword> render as inline code; overload crefs link to the overload heading
File names
New ApiMark.Core.FileNameSanitizer guarantees legal, collision-free names across DotNet, C++ and VHDL (reserved Windows names, illegal characters, case twins, explicit generic-interface members); FileMarkdownWriterFactory rejects illegal segments.
Breaking changes
Generic type pages are renamed (Foo1.md->Foo-1.md`), and explicit-interface member pages and some colliding names change. Migration notes are in the user guide.
C++ clang-dependent tests cannot run on the authoring machine (clang not installed). ClangHangs test timeout raised from 300 ms to 5000 ms (flaky under load; fails on the base commit too).
Code review: no issues. Formal review: one finding (sanitizer collision), fixed and tested.
Follow-up
A registry-based naming scheme (Foo{2}.md, -N fallback, documented rules) is planned as a separate PR.
This blank line terminates the Markdown table before the H3 row, so the member row is rendered as ordinary text instead of a table row. Keep the H3 row adjacent to the H2 row.
This new path-conventions note says all generated names use GetTypeFileName/GetSanitizedMemberFileName, but the path patterns immediately below still prescribe FlattenArity(type.Name) and raw memberName/lowerKey values. That contradicts the implemented collision and reserved-name handling (and the documented Foo-1 breaking change), so the design document still directs readers to stale paths; please update those patterns to the actual helpers and sanitized outputs.
Correct link version warning when an explicit override is set
src/ApiMark.MSBuild/ApiMarkTask.cs:511
This warning is inaccurate when ApiMarkLinkVersion is set: ResolveLinkVersion gives that explicit override precedence, but the message always says {version} uses PackageVersion and tells the user to set the override. Either suppress the mismatch warning when an explicit override is present or report that the override wins.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Unresolved moderate findings remain in filename sanitization, inheritance handling, and external type-link resolution.
0 open findings
Previously missed (1)
In code that hasn't changed since last review
Model C# name hiding across member kinds and overloads
src/ApiMark.DotNet/DotNetEmitter.cs:631
The inherited-member suppression key does not model C# name hiding across member kinds or overloads. A derived void M(string) hides the base M(int) from member lookup, and a derived field/property named M hides base methods named M, but these keys remain M:(...) versus N:M, so the base members are still listed under Inherited Members. Build the suppression state around hidden member names (while separately handling overrides/overloads) so the listing matches the actual derived-type surface.
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
Fixes the DotNet output regressions and gaps reported against ApiMark 0.5.8 (found while documenting Plexus), and adds regression tests so each fix is guarded by exact-output assertions.
Reported issues fixed
void?return types in nullable contexts;paramsmodifier;virtual/override/abstract/sealed/newmodifiers and a protected marker in overview rows?, and C# tuple syntaxFoo<T>page titles, Type Parameters tables (types and methods), constraints<inheritdoc/>resolved from reference XML or treated as documentedAPI Referencebreadcrumb on every page, "Start here" and Key Types inapi.mdApiMarkLinkVersion>PackageVersion>Versionprecedence with a mismatch warning; prose<see cref>and nested-type crefs link<paramref>,<typeparamref>and<see langword>render as inline code; overload crefs link to the overload headingFile names
ApiMark.Core.FileNameSanitizerguarantees legal, collision-free names across DotNet, C++ and VHDL (reserved Windows names, illegal characters, case twins, explicit generic-interface members);FileMarkdownWriterFactoryrejects illegal segments.Breaking changes
Foo1.md->Foo-1.md`), and explicit-interface member pages and some colliding names change. Migration notes are in the user guide.Validation
lint.ps1clean; DotNet (net8/9/10), Core, MSBuild, Tool and VHDL tests pass.ClangHangstest timeout raised from 300 ms to 5000 ms (flaky under load; fails on the base commit too).Follow-up
Foo{2}.md,-Nfallback, documented rules) is planned as a separate PR.