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
Fixes three remaining cosmetic ApiMark 0.5.5 issues found building DemaConsulting.Bicameral.Core (ApiMarkVisibility=All):
<br/> and <code> inside <remarks>/<summary> were dropped/unescaped. The shared XML-doc rendering dispatch had no cases for these elements, so <br/> silently vanished and <code> content leaked raw Markdown-sensitive characters (e.g. regex-generator patterns with backslashes/brackets). Now <br/> renders as a paragraph break, and <code> renders as an inline code span (single line) or a fenced code block (multi-line), with a sentinel-token placeholder scheme protecting internal code whitespace from the existing text-normalization pass.
Runs of 2-3 blank lines around lists/code blocks (markdownlint MD012).NormalizeDocumentationText now collapses any run of 2+ consecutive blank lines down to exactly one.
<see cref="Type.Member"/> rendered as plain, unlinked text. Member-cref display text (Type.Member) is now wrapped in an inline code span, per the user's own suggested fallback (full page-link resolution remains out of scope — XmlDocReader has no page-resolution context). Type-only and constructor cref display text is left unwrapped, unchanged.
Changes
src/ApiMark.DotNet/XmlDocReader.cs: new br/code rendering cases, placeholder-based whitespace protection for fenced code blocks, blank-line-run collapsing, member-cref code-span wrapping.
test/ApiMark.DotNet.Tests/XmlDocReaderTests.cs: new/updated tests covering all three fixes, including a literal regex-generator-style example and a whitespace-preservation regression test.
docs/design/, docs/verification/, docs/reqstream/ for api-mark-dot-net/xml-doc-reader: updated to reflect the new behavior, with full traceability.
docs/reqstream/api-mark-dot-net.yaml: linked the three new requirements into the parent decomposition (avoids orphaned-requirement lint failure).
Validation
Full solution build: 0 warnings / 0 errors (net8.0/net9.0/net10.0).
ApiMark.DotNet.Tests: 396/396 passing on all 3 TFMs.
…mber crefs
- XmlDocReader: render <br/> as paragraph breaks and <code> as inline code
spans or fenced code blocks (dedented, backtick-run-aware fencing) within
<remarks>/<summary>, protecting fenced-block whitespace from the per-line
normalizer via a placeholder/token substitution scheme threaded through
AppendNodeText/AppendElementText and restored in GetDocumentationText.
- NormalizeDocumentationText: collapse runs of 2+ consecutive blank lines to
a single blank line (MD012), independent of NormalizeSingleLine.
- FormatCref/FormatMemberReference: return (Text, IsMemberReference) tuples
so GetInlineReferenceText can wrap M:/P:/F:/E: cref display text in an
inline Markdown code span via AppendMarkdownCodeSpan, while leaving
type-only (T:) and constructor (#ctor) cref text unwrapped.
- Tests: add 13 new XmlDocReaderTests covering br paragraph breaks, inline
vs fenced code dispatch, exact whitespace preservation in fenced blocks,
the reported regex-generator Pattern:/Explanation: repro case, blank-line
run collapsing, and member-cref vs type-cref code-span wrapping; update 7
existing tests plus one DotNetGeneratorTests assertion for the new
backtick-wrapped member-cref rendering.
- Docs: update xml-doc-reader design and verification docs for the new
rendering/normalization behavior, and add three reqstream requirements
(RenderBrAndCodeInRemarksAndSummary, CollapseExcessBlankLineRuns,
WrapMemberCrefDisplayInCodeSpan) tagged to the new/updated tests.
- .cspell.yaml: add 'dedenting' and 'seealso' dictionary entries used by
the updated documentation.
- XmlDocReaderTests: replace weak Assert.Contains with an exact
Assert.Equal in XmlDocReader_GetSummary_WithSeeGenericTypeCref_
FormatsWithTypeParameters, so a backtick-wrapping regression on
type-only (T:) cref display text would be caught.
- XmlDocReaderTests: add XmlDocReader_GetSummary_SeeCrefToConstructor_
RendersUnwrappedTypeName, covering the previously-untested M:Type.#ctor
cref path to confirm it renders the bare type name with no inline
code-span wrapping.
- docs/verification: add Test Scenarios entries for both tests, backing
the existing T:/#ctor unwrapped-cref acceptance criteria bullet.
- docs/reqstream: link both test names under the
WrapMemberCrefDisplayInCodeSpan requirement for traceability.
Resolves orphaned-requirement lint failure for RenderBrAndCodeInRemarksAndSummary, CollapseExcessBlankLineRuns, and WrapMemberCrefDisplayInCodeSpan, flagged by the formal review.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…pace, generic cref escaping
- GetParams/GetExceptionDetails now use GetSingleLineDocumentationText so a
multi-line <code>/<br/> in a <param>/<exception> description flattens to a
single line instead of corrupting the Markdown table cell it is written
into.
- GetSingleLineDocumentationText now creates and supplies a codeBlocks
placeholder map, and AppendCodeElementText registers the inline-code-span
branch as a placeholder when one is supplied, protecting internal
whitespace from the single-line normalizer's collapsing pass.
- FormatTypeArity gains a forCodeSpan parameter (threaded through FormatCref/
FormatMemberReference/FormatTypeName) so a member cref to a generic type
renders unescaped angle brackets inside its code span (List<T>.Add()),
instead of the prose-escaped form (List\<T\>.Add()) showing literal
backslashes.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…doc comment
- GetExceptionDetails and GetParams each had two sibling <remarks> elements;
XmlDocReader only reads the first via member.Element("remarks"), so the
second block's table-safety explanation was silently dropped from
generated docs. Merged into a single <remarks> block for each method.
- AppendNodeText's codeBlocks parameter doc and GetDocumentationText's
summary claimed GetDocumentationText was the only call site supplying a
non-null placeholder map; GetSingleLineDocumentationText also supplies one.
Updated both doc comments to name both entry points.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
When a multi-line <code> element is flattened for a single-line context, NormalizeSingleLine(dedented) collapses every run of spaces/tabs inside the code before the placeholder is registered. This contradicts the stated whitespace-preservation behavior and corrupts patterns with significant spacing when they occur in summaries, parameter descriptions, or exception descriptions; flatten the line breaks while preserving each line's internal whitespace, then register the result.
Protected-path guarantee incorrectly includes unprotected <c> elements
This design statement includes <c> in the protected-path guarantee, but <c> is still rendered directly at XmlDocReader.cs:789-799 and does not use codeBlocks; only the new <code> branch is protected. Please remove <c> from this sentence (or update the implementation if protection for <c> is intended) so the design does not promise whitespace preservation that the code does not provide.
…n single-line flatten
- GetInlineReferenceText no longer calls FormatAsInlineCodeSpan on empty
text, fixing an IndexOutOfRangeException for a malformed member cref
(e.g. <see cref="M:"/>) whose formatted display text is empty.
- AppendCodeElementText now flattens a multi-line <code> element into a
single-line inline span via a new FlattenCodeToSingleLine helper instead
of NormalizeSingleLine, so each line's significant internal whitespace
(multiple spaces, tabs) survives; only the line-boundary collapses to a
single joining space.
- Corrected the design doc's protected-path guarantee wording: <c>
elements are not protected by the codeBlocks placeholder mechanism,
only <code> elements are.
- Added regression tests for both fixes and amended the xml-doc-reader
verification/reqstream docs with the new test references.
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 three remaining cosmetic ApiMark 0.5.5 issues found building DemaConsulting.Bicameral.Core (
ApiMarkVisibility=All):<br/>and<code>inside<remarks>/<summary>were dropped/unescaped. The shared XML-doc rendering dispatch had no cases for these elements, so<br/>silently vanished and<code>content leaked raw Markdown-sensitive characters (e.g. regex-generator patterns with backslashes/brackets). Now<br/>renders as a paragraph break, and<code>renders as an inline code span (single line) or a fenced code block (multi-line), with a sentinel-token placeholder scheme protecting internal code whitespace from the existing text-normalization pass.NormalizeDocumentationTextnow collapses any run of 2+ consecutive blank lines down to exactly one.<see cref="Type.Member"/>rendered as plain, unlinked text. Member-cref display text (Type.Member) is now wrapped in an inline code span, per the user's own suggested fallback (full page-link resolution remains out of scope —XmlDocReaderhas no page-resolution context). Type-only and constructor cref display text is left unwrapped, unchanged.Changes
src/ApiMark.DotNet/XmlDocReader.cs: newbr/coderendering cases, placeholder-based whitespace protection for fenced code blocks, blank-line-run collapsing, member-cref code-span wrapping.test/ApiMark.DotNet.Tests/XmlDocReaderTests.cs: new/updated tests covering all three fixes, including a literal regex-generator-style example and a whitespace-preservation regression test.docs/design/,docs/verification/,docs/reqstream/forapi-mark-dot-net/xml-doc-reader: updated to reflect the new behavior, with full traceability.docs/reqstream/api-mark-dot-net.yaml: linked the three new requirements into the parent decomposition (avoids orphaned-requirement lint failure).Validation
ApiMark.DotNet.Tests: 396/396 passing on all 3 TFMs.fix.ps1/lint.ps1: clean (yamllint, cspell, markdownlint, reqstream, versionmark, reviewmark, sysml2tools, dotnet format).ApiMark-DotNet-XmlDocReaderreview-set): one medium orphaned-requirement finding, fixed in a follow-up commit; re-verified clean.Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com