[jknowles]

No Gitea issue yet; the maintainer may file one.

What changed

The roxygen comments are written in markdown (**bold**, backticks, [cog_x()] links, bullet lists), but DESCRIPTION had no Roxygen: list(markdown = TRUE), so every .Rd file carried that syntax literally.

• DESCRIPTION: adds Roxygen: list(markdown = TRUE), placed above RoxygenNote. RoxygenNote itself is unchanged.
• man/: regenerated with roxygen2 7.3.3, which matches RoxygenNote. 16 .Rd files changed, which is every page in man/.
• R/balance_caveats.R: one roxygen line, escaping literal brackets (details below).

18 files in total. No code changed. No .Rd file was edited by hand.

Wording I had to alter

None. The one roxygen source change is an escape, not a wording change:

• R/balance_caveats.R:56: [min year, max year] → \[min year, max year\]. Markdown mode read the brackets as a link to a topic named "min year, max year" and warned. That block is @noRd, so no page shows it either way.

One side effect is worth knowing about. Text that was silently missing from the rendered pages is now there. Without markdown mode, a bare % starts an Rd comment, so the rest of its line was dropped. Markdown mode escapes it (\%), which restores 11 truncated lines across six pages, coming from six roxygen lines:

• cog_spending, cog_revenue, cog_balances: "7**% of the no-filter floor.**"
• cog_fiscal_periods, cog_survey_year: "99**% of its government-years have no usable**", "5**% to 11% in FY1978**", "3**% in every other year.**"
• cog_peer_compare: "−32.7**% to +251.0% across 24 years on**"; and in the code example, filter(role %in% c("target", "peer")) |> had everything from %in% on cut.

The commit message says "seven places". The correct count is the 11 lines above. I tried to amend the message before opening this PR, but the sandbox refused the force-push, so the commit message stands as pushed.

How I reviewed every changed page

1. Rendered-text diff. Each old and new .Rd went through tools::Rd2txt(), and I diffed the words after ignoring the characters markdown consumes (backticks, *, brackets, quote styles). All 42 differing runs are explained:

   • the % restorations above;
   • *word* now rendering as emphasis;
   • L-- keeping its two hyphens instead of becoming a dash;
   • whitespace around code spans.

   No word was lost, and no stray link appeared.

2. Raw .Rd read. I read every added line of all 16 pages, about 700 lines.

   • No backticks, **, ]( or [cog_ remain.
   • All 12 distinct \link targets exist.
   • Markdown produced 12 \itemize blocks, one \enumerate (the intended four-step list in cog_gov_search), one \preformatted block (cog_peer_compare's example), 37 \strong and 6 \emph.
   • R/fiscal.R:218 begins a wrapped line with "30)". Markdown only starts a list mid-paragraph at 1, so no list was created.
   • The #59); line start in cog_spending is neither a heading nor an Rd directive.

3. tools::checkRd() on all 16 new files: no findings apart from the existing non-ASCII notes. DESCRIPTION declares Encoding: UTF-8, so R CMD check raises no notes for them.

Pages I did not read: none. All 16 pages in man/ changed, and I read all of them.

Checks

• roxygen warnings: with markdown on, the run warns only about the two pre-existing @noRd must not be followed by any text at R/manifest.R:130 and R/views.R:124. The bracket warning is fixed.
• R CMD build --no-manual + R CMD check --no-manual: every Rd check reports OK, the same as before ("Rd files", "Rd metadata", "Rd cross-references", "missing documentation entries", "code/documentation mismatches", "Rd \usage sections", "Rd contents"). No new Rd warnings. Overall status is 1 WARNING and 2 NOTEs, unchanged from main:
  • WARNING: the sandbox has no en_US.UTF-8 locale.
  • NOTE: .roborev.toml is a hidden file.
  • NOTE: installed size.
• pkgdown::check_pkgdown(): no problems found.
• pkgdown::build_reference(examples = FALSE) in a scratch copy: all reference pages build. The HTML shows real <strong> and linked cog_find_peers(), and no literal **.
• Full test suite: 1,193 expectations, 0 failed, 2 skipped (opt-in live-corpus tests). test-peer-summary-scope.R, which asserts text in man/cog_peer_compare.Rd, still passes.
• Local deviation, as on earlier PRs: the sandbox cannot reach extensions.duckdb.org, so checks and tests ran on a scratch copy with cog_open()'s INSTALL httpfs; LOAD httpfs; line removed. That is not in the commit.

Not verified

• Hosted rendering. I did not run pkgdown::build_site() or view the hosted reference pages.
• Other platforms. The local checks ran on R 4.3.3 / Ubuntu 24.04 only. CI covers macOS, Windows, and Ubuntu (release and devel).

🤖 Generated with Claude Code

https://claude.ai/code/session_01Qbe6u2h83wgZdTgJgE4Xh5

[github-actions]

Thanks for this — and one thing worth knowing before it happens.

This repository is a mirror. Development happens on Gitea at
gitea.civilytics.org/Civilytics/uscogdata. Your pull request will be fetched
from here, landed there, and synced back.

Because that merge preserves your commits at their original SHAs, GitHub will
mark this pull request "Merged" on its own — without anyone visibly clicking
the Merge button, and possibly without a review comment on this page first.

If your pull request closes as "Merged" and nobody appears to have merged it,
that is the normal, successful outcome — not a rejection.

If it is not going to be merged, you will get an actual reply saying so.

Substantial contributions get a ctb entry in DESCRIPTION, which surfaces in
citation("uscogdata"). There is no CLA and no DCO sign-off.

Full details: CONTRIBUTING.md.