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 nested-type links, list rendering, cref member context, and remarks-only placeholder - #52
Fixes four rendering bugs reported against ApiMark 0.5.4, found while building DemaConsulting.Bicameral.Core (ApiMarkVisibility=All):
Broken nested-type links (47 links) — links to a nested type from any page other than its parent's nested-types table pointed to <docs root>/<NestedName>.md instead of .../Parent/NestedName.md. Caused by nested types reporting an empty Namespace in Mono.Cecil metadata; TypeLinkResolver now falls back to the declaring type's namespace.
<list type="number"/"bullet"/"table"> rendered as one inline paragraph — XmlDocReader now renders real multi-line Markdown lists on member/type pages, and a new GetSummaryMarkdown API produces a single-line, list-aware summary for table cells (including the <listheader> labels, which are preserved rather than dropped in this compact form).
<see cref="Type.Member"/> lost its type context — rendered as the bare member name. FormatMemberReference now renders Type.Member as display text (XmlDocReader has no page-resolution context, so this does not add a hyperlink).
"No description provided." shown above generator remarks — summary-less members with <remarks> (e.g. [GeneratedRegex] methods) now suppress the placeholder whenever remarks are present, consistently at type and member level in both the gradual-disclosure and single-file emitters.
Testing
New fixtures: NestedTypeConsumerClass, TwoLevelNestedClass, SummaryListDocClass.
New/updated tests cover nested-type links from various reference kinds (parameter, return, field, generic argument) and depths (two-level nesting), numbered-list rendering on member pages, inline <listheader> preservation in compact summaries, cref Type.Member display text, and remarks-only placeholder suppression at both type and member level.
Full solution build: 0 warnings/errors.
ApiMark.DotNet.Tests: 381/381 passing across net8.0/net9.0/net10.0.
fix.ps1 / lint.ps1: clean (exit 0).
Code-review and formal-reviews for all four affected review-sets (ApiMark-DotNet-TypeLinkResolver, ApiMark-DotNet-XmlDocReader, ApiMark-DotNet-DotNetEmitterGradualDisclosure, ApiMark-DotNet-DotNetEmitterSingleFile) passed/approved.
…ks-only placeholder
Four rendering bugs reported against ApiMark 0.5.4:
1. Links to nested types resolved to the docs root instead of the
parent type's folder, because nested types report an empty
Namespace in Mono.Cecil metadata. TypeLinkResolver now falls back
to the declaring type's namespace when resolving a nested type's
page path, matching the nested-types table's link construction.
2. <list type="number"/"bullet"/"table"> XML-doc content was always
flattened to a single inline paragraph. XmlDocReader now renders
lists as real multi-line Markdown on member/type pages (with a
blank line before the list and following text as a new paragraph),
while table cells still receive a single-line, list-aware summary
via the new GetSummaryMarkdown API.
3. <see cref="Type.Member"/> inside text rendered as the bare member
name, losing which type it belonged to. FormatMemberReference now
renders "Type.Member" and links to the member's page when it
exists.
4. Summary-less members with generated <remarks> (e.g. [GeneratedRegex]
methods) showed a "No description provided." placeholder above the
remarks. The placeholder is now suppressed whenever remarks content
is present, consistently at both type and member level across the
gradual-disclosure and single-file emitters.
Adds fixtures (NestedTypeConsumerClass, TwoLevelNestedClass,
SummaryListDocClass) and tests covering nested-type links from various
reference kinds/depths, numbered-list rendering, cref member links,
and remarks-only placeholder suppression. Updates design, reqstream,
and verification docs for the four affected units: TypeLinkResolver,
XmlDocReader, DotNetEmitterGradualDisclosure, DotNetEmitterSingleFile.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Fixes .NET documentation rendering for nested-type links, XML lists, cref member formatting, and remarks-only descriptions.
Changes:
Correct nested-type page paths, including deep nesting.
Add multi-line and compact list rendering.
Improve cref member display.
Suppress redundant placeholders when remarks exist.
Expand regression tests and documentation.
[Moderate] Compact table summaries currently drop <listheader> labels.
[Nit] Claimed cref member-page linking is not implemented; align the implementation or description.
Address PR #52 review: AppendInlineMarkerList only read <item>
elements, so a <list type="table">'s <listheader> column labels were
silently dropped in single-line summary/table-cell contexts (unlike
the multi-line AppendTableList path, which keeps them). The header is
now rendered first (bolded), matching the multi-line AppendMarkerList
behavior. Extends the existing inline-table-list test to assert the
header text is preserved.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The new type-level placeholder branch in WriteTypeHeaderSections is not covered by the gradual-disclosure tests: the added remarks-only regression exercises a member, while the type-level case is tested only in the separate single-file emitter. Please add a synthetic remarks-only type case here and assert that its gradual-disclosure type page contains the remarks and omits the placeholder, so this changed path cannot regress independently.
…evel remarks-only test
Address two review findings on PR #52:
1. The compact (single-line) list-header rendering added for
"Inline table lists drop listheader labels" wrapped the already
partially-bolded FormatTermDescription output in another "**...**"
pair, producing malformed Markdown such as "****Name** — Detail**"
whenever a <listheader> had both a term and a description. Added a
dedicated FormatListHeaderText helper that bolds the full header
label itself (both parts individually, e.g. "**Name** — **Detail**")
without double-wrapping, used by both AppendMarkerList (multi-line
bullet/number lists) and AppendInlineMarkerList (compact form) so
neither path double-bolds. Extended the existing inline table-list
test with an exact-output assertion to guard against regressing
this.
2. Added the missing gradual-disclosure regression test for the
type-level placeholder-suppression branch in
WriteTypeHeaderSections: the prior remarks-only coverage only
exercised a member page (GeneratedRegexClass.DigitsRegex); this adds
a synthetic remarks-only override for SampleClass and asserts its
own type page shows the remarks and omits the placeholder, so this
changed path cannot regress independently of the member-level path.
Updates reqstream requirements and verification docs for XmlDocReader
and DotNetEmitterGradualDisclosure accordingly.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…evel remarks-only test
Address two review findings on PR #52:
1. The compact (single-line) list-header rendering added for
"Inline table lists drop listheader labels" wrapped the already
partially-bolded FormatTermDescription output in another "**...**"
pair, producing malformed Markdown such as "****Name** — Detail**"
whenever a <listheader> had both a term and a description. Added a
dedicated FormatListHeaderText helper that bolds the full header
label itself (both parts individually, e.g. "**Name** — **Detail**")
without double-wrapping, used by both AppendMarkerList (multi-line
bullet/number lists) and AppendInlineMarkerList (compact form) so
neither path double-bolds. Extended the existing inline table-list
test with an exact-output assertion to guard against regressing
this.
2. Added the missing gradual-disclosure regression test for the
type-level placeholder-suppression branch in
WriteTypeHeaderSections: the prior remarks-only coverage only
exercised a member page (GeneratedRegexClass.DigitsRegex); this adds
a synthetic remarks-only override for SampleClass and asserts its
own type page shows the remarks and omits the placeholder, so this
changed path cannot regress independently of the member-level path.
Updates reqstream requirements and verification docs for XmlDocReader
and DotNetEmitterGradualDisclosure accordingly.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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 four rendering bugs reported against ApiMark 0.5.4, found while building DemaConsulting.Bicameral.Core (
ApiMarkVisibility=All):<docs root>/<NestedName>.mdinstead of.../Parent/NestedName.md. Caused by nested types reporting an emptyNamespacein Mono.Cecil metadata;TypeLinkResolvernow falls back to the declaring type's namespace.<list type="number"/"bullet"/"table">rendered as one inline paragraph —XmlDocReadernow renders real multi-line Markdown lists on member/type pages, and a newGetSummaryMarkdownAPI produces a single-line, list-aware summary for table cells (including the<listheader>labels, which are preserved rather than dropped in this compact form).<see cref="Type.Member"/>lost its type context — rendered as the bare member name.FormatMemberReferencenow rendersType.Memberas display text (XmlDocReaderhas no page-resolution context, so this does not add a hyperlink).<remarks>(e.g.[GeneratedRegex]methods) now suppress the placeholder whenever remarks are present, consistently at type and member level in both the gradual-disclosure and single-file emitters.Testing
NestedTypeConsumerClass,TwoLevelNestedClass,SummaryListDocClass.<listheader>preservation in compact summaries, crefType.Memberdisplay text, and remarks-only placeholder suppression at both type and member level.ApiMark.DotNet.Tests: 381/381 passing across net8.0/net9.0/net10.0.fix.ps1/lint.ps1: clean (exit 0).ApiMark-DotNet-TypeLinkResolver,ApiMark-DotNet-XmlDocReader,ApiMark-DotNet-DotNetEmitterGradualDisclosure,ApiMark-DotNet-DotNetEmitterSingleFile) passed/approved.Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com