Skip to content

docs: fix stale v2.0 documentation and remove LLM artefacts#269

Merged
ms609 merged 1 commit into
cpp-searchfrom
docs-v2-audit
Jul 9, 2026
Merged

docs: fix stale v2.0 documentation and remove LLM artefacts#269
ms609 merged 1 commit into
cpp-searchfrom
docs-v2-audit

Conversation

@ms609

@ms609 ms609 commented Jul 9, 2026

Copy link
Copy Markdown
Owner

Audit of the documentation surface touched by the 2.0.0 release, checking each claim against the current implementation. Findings were gathered by clustered read-only passes; every fix below is backed by the code it contradicts.

Stale / incorrect claims

  • large preset docs described a preset that no longer exists. large is now an alias of thorough (presets$large <- presets$thorough) with maxReplicates raised to 500, but the roxygen, a SearchControl() comment, and search-algorithm.Rmd / tree-search.Rmd still described the retired bespoke preset (biased Wagner, simulated annealing, reduced cycles).
  • default preset documented as "12 ratchet"; it is 6 (ratchetCycles = 6L).
  • Vignette preset claims contradicted SearchControl() defaults: adaptiveStart "disabled in large" (it is TRUE), ratchetTaper / annealCycles "enabled in thorough/large" (both off), consensusStableReps "default 3" (default 0), and the auto-selection tip/pattern thresholds.
  • Profile parsimony "binary only (max 2 states)" in MaximizeParsimony() — multi-state is supported (Carter 1990 for 2 states, Maddison & Slatkin 1991 for 3–5, Monte Carlo beyond). ConcordantInformation() carried the same stale two-state restriction.
  • PrepareDataProfile(): documented a split.sizes bootstrap entry it never writes, and claimed simplification happens "with a warning" when only the inapplicable-token case emits a message.
  • WideSample() @return said "uniform sample"; it returns a Max-Min diverse subset (the function's whole point).
  • fractional-weight default documented as 1000L; it is 1260L.
  • Implied-weight fit formula rendered as k / e + k; corrected to k / (e + k) (propagates to inheriting man pages).

LLM artefacts removed

  • The "reflects island structure, not a cap" defensive framing in the Completeness section. (The "256 is not hard-coded anywhere" aside that prompted this audit was already removed on the branch tip by Replace Morphy with native kernel for inapplicable data #251.)
  • NEWS.md: the "This addresses a common complaint…" defensive aside, the empty ## Other improvements section, and a duplicated PaintCharacters() bullet.

Deliberately left for the maintainer

man/*.Rd regenerated with roxygen2 8.0.0.

🤖 Generated with Claude Code

Audit of the documentation surface touched by the 2.0.0 release.

Stale/incorrect claims corrected:
- Preset docs described the retired bespoke `large` preset (biased Wagner,
  annealing, reduced cycles); `large` is now an alias of `thorough` with
  maxReplicates=500.  Fixed in MaximizeParsimony roxygen, the SearchControl
  comment, and the search-algorithm / tree-search vignettes.
- `default` preset documented as 12 ratchet cycles; it is 6.
- Vignette preset claims about adaptiveStart, ratchetTaper, annealCycles and
  consensusStableReps contradicted the actual SearchControl defaults / preset
  values.
- MaximizeParsimony profile-parsimony docstring claimed binary-only
  (max 2 states); multi-state is supported (Carter 1990 / Maddison &
  Slatkin 1991 / Monte Carlo).  ConcordantInformation carried the same
  stale two-state restriction.
- PrepareDataProfile: `bootstrap` attribute documented a `split.sizes`
  entry it never writes; "with a warning" overstated (only the
  inapplicable-token simplification emits a message).
- WideSample `@return` said "uniform sample"; it returns a Max-Min
  diverse subset.
- fractional-weight default documented as 1000L; it is 1260L (NEWS.md).
- Implied-weight fit formula rendered as `k / e + k`; corrected to
  `k / (e + k)` (propagates to inheriting man pages).

LLM artefacts removed:
- The "reflects island structure, not a cap" framing in the Completeness
  section (the "256 is not hard-coded" aside was already removed on the
  branch tip by #251).
- NEWS.md: the "common complaint" defensive aside, the empty
  "Other improvements" section, and a duplicate PaintCharacters bullet.

man/*.Rd regenerated with roxygen2.

Not addressed here (left for the maintainer): the "To integrate into 2.0.0
notes" scaffold in NEWS.md now also holds #251's breaking-change bullets, and
the "renamed to Morphy()" line is stale since #251 removed Morphy() — final
integration of that section is #251's to make.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@ms609 ms609 merged commit 775631b into cpp-search Jul 9, 2026
2 checks passed
@ms609 ms609 deleted the docs-v2-audit branch July 9, 2026 10:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant