docs: fix stale and incorrect code comments across the package

[eonist]

Resolves the audit in #11.

Every changed line in this PR is a comment. The only non-comment line in the diff gains a trailing comment; nothing else moves. All 17 tests pass, build is clean with no warnings.

Note

Stacked on #9, so this PR targets fix/safe-hardening-and-platform-floor rather than main. Three of the fixes (the macOS 13 floor references) only make sense on top of that branch. Retarget to main once #9 merges.

What changed

Nine false claims corrected

Comment	Was	Actually
BlockParser type doc	"Top-level only — list-item children are handled recursively inside MarkdownListView"	parse recurses into itself; MarkdownListView never calls it
MarkdownListView type doc	"nested lists via listDepth"	the property is depth; listDepth is the outgoing argument label
MarkdownStyle.textPrimary	"headings and body content"	table cells only
MarkdownStyle.radiusSmall	"inline code chips and code block containers"	code block container only
MarkdownStyle.init	"Use MarkdownStyle.runBot… rather than constructing a value directly"	that symbol does not exist in this package
MarkdownCodeBlockView.language	"Lowercased language identifier"	passed through verbatim
MarkdownCodeBlockView / MarkdownHighlighter	returns nil on "unknown language"	unknown languages are auto-detected, never nil
InlineTextView type doc	design justified by a macOS 26 deprecation	floor is macOS 13; the real reason is per-run intents
MarkdownRenderLog	"Internal diagnostics"	both renderLogKind extensions are public API
MarkdownTableView	"Cell widths are bounded at 220pt"	the 220 is in MarkdownTableCellView
MarkdownDetectorTests case 2	credited to the cubic bypass	clears the density floor on its own

Verified, not assumed

Three of those were checked by running the code rather than reading it:

BlockParser recursion — parsing - outer / - inner / - deepest yields a model 3 levels deep; 40 nested > markers yield 40. Both built entirely inside BlockParser.parse.

Fence-language casing — #11 §3.6 left this open as a behaviour decision. Resolved as a doc fix, because "SWIFT", "Swift" and "swift" produce byte-identical highlighted output; highlight.js matches case-insensitively. No code change was needed.

That probe also turned up a finding the audit missed: "bogus-lang" does not return nil — it comes back with 6 coloured runs, distinct from both plaintext and swift. highlight.js auto-detects when it doesn't recognise a name. So two comments promising a nil-on-unknown-language path were describing a branch that is never taken, and the ?? "plaintext" fallback in both call sites turns out to be load-bearing: it's what stops untagged output from being auto-detected as some guessed syntax. Both now say so.

Detector boundary case 2 — against the running detector:

case2 shortDense:  score=5 lines=15  density=0.333 (>=0.10: true)   cubic=8.33
case4 mediumPass:  score=7 lines=134 density=0.052 (>=0.10: false)  cubic=2.56

Case 2 passes on density; it does not isolate the cubic bypass the comment credited. Case 4 is the only one of the six that does — and it now says "retune the cubic constant and this is the case that moves."

Provenance and dead references removed

20 file headers naming RunBot, ten comments describing RunBot internals, five issue numbers from another tracker (#2379, #2394, #2600, #2731, #2740), and four symbols that live elsewhere (cleanLogText, StepLogView.loadLog(), MarkdownLogView, MarkdownStyle+RunBot.swift). Also "Option A" and "per repository policy", neither of which named anything findable in this repo.

Each comment's rule was kept; only its RunBot instance was dropped. The ANSI-stripping precondition on MarkdownDetector, for instance, is a real contract the package can't enforce, so it stays — minus the migration plan for another repo's refactor.

Review directives removed from public API docs

Two doc comments addressed a code reviewer, and both shipped in DocC and Xcode Quick Help:

• "This is NOT a bug in the detector… Do not flag this as a double-parse in the detector itself."
• "Do not remove it as dead code without explicitly changing that contract."

Both now state the underlying fact for a caller instead. Relatedly, the auto-enable gate was described in three places in MarkdownDetector — which is how one of them drifted, and how DetectResult's copy came to omit the score >= 3 floor. detect(_:) is now the single description; the other two point at it.

Comments added where behaviour is surprising

• MarkdownCodeBlockView ↔ HighlightPrewarmer — both compute the cache-key language independently. The cache key holds the raw string, so any divergence makes every prewarmed entry miss and silently turns prewarming into an expensive no-op. Both sites now say to keep them identical.
• BlockParser.parse — recursion depth is bounded only by input, and a Task's cooperative stack is much smaller than the main thread's, so parseAsync overflows shallower. This is the warning that the old "top-level only" comment displaced.
• parseAsync — does not check Task.isCancelled, though DESIGN.md asks callers to respect cancellation. Now stated, matching how preWarmHighlighter already documents its own behaviour.
• Inert links — the accent colour is applied outside the scheme guard, so a rejected javascript: link looks exactly like a working one. Marked as the deliberate trade-off it is.
• Clear underline — AttributedString auto-underlines .link runs with no way to disable it, so the underline is drawn in clear. Reads like a mistake without the note.
• parseCells — pads short rows and silently drops cells past the delimiter width. Only the padding direction was documented or tested.
• Three Color(nsColor:) defaults — with import AppKit, the entire iOS blocker.
• Package.swift — macOS 13 is set by SwiftUI Grid; v12 fails on that symbol alone.

Boilerplate removed

Six identical /// SwiftUI view body — see type-level doc for rendering contract. comments, on views whose type docs mostly had no contract to see. Deleted, and the type docs they pointed at now state one — MarkdownListView explains how nesting is actually resolved, MarkdownTableCellView explains the width cap.

Deliberately not done

• The nested ternary in MarkdownTableCellView:31 (Code comment audit: stale RunBot provenance, nine false claims, and the comments worth adding #11 §5.9) is commented, not extracted. Extracting it is provably equivalent over all four ColumnAlignment cases, but it would be the only behaviour-touching line in the PR and break the "comments only" guarantee. Worth its own one-line change.
• The MarkdownHighlighter cache — the comment claiming no measurement exists now cites the ~54 µs figure from Package assessment: correctness, performance, platform reach, and packaging #8 §2.2. Replacing the linear scan stays with Package assessment: correctness, performance, platform reach, and packaging #8.

Refs #11

[greptile-apps]

Greptile Summary

This documentation-only PR corrects stale or inaccurate comments, removes product-specific provenance, and documents several non-obvious parser, highlighter, rendering, and platform constraints.

• Aligns public API documentation with current parsing, detection, styling, table, and highlighting behavior.
• Replaces external product and issue references with package-local contracts and rationale.
• Adds maintenance warnings around recursive parsing, cancellation, cache-key consistency, safe links, table normalization, and macOS availability.

Confidence Score: 5/5

The PR appears safe to merge because it changes comments only and no concrete inaccurate or behavior-affecting change remains.

The updated documentation is consistent with the inspected parsing, rendering, detection, styling, table, and highlighting paths, with no accepted blocking or non-blocking findings.

Important Files Changed

Filename	Overview
Package.swift	Documents the macOS 13 deployment floor and rationale for revision-pinned dependencies without changing package configuration.
Sources/MarkdownKit/MarkdownDocumentView.swift	Corrects parser recursion documentation and records cancellation and deep-input stack limitations.
Sources/MarkdownKit/Highlighting/MarkdownHighlighter.swift	Clarifies unknown-language auto-detection, failure fallback, and bounded-cache behavior.
Sources/MarkdownKit/Rendering/MarkdownCodeBlockView.swift	Documents verbatim language handling, plaintext fallback selection, and cache-key alignment with prewarming.
Sources/MarkdownKit/Rendering/MarkdownInlineRenderer.swift	Clarifies attributed-text intent handling, safe link activation, and underline suppression.
Sources/MarkdownKit/Styling/MarkdownStyle.swift	Corrects token usage documentation and identifies the AppKit-derived color defaults relevant to portability.
Sources/MarkdownKit/Model/MarkdownTableModel.swift	Documents delimiter-defined table width and silent normalization of ragged rows.
Tests/MarkdownKitTests/MarkdownDetectorTests.swift	Corrects comments identifying which detector boundary case uniquely exercises the cubic bypass.

_{Reviews (1): Last reviewed commit: "docs: fix stale and incorrect code comme..." | Re-trigger Greptile}