Skip to content

Update template to modern Carp idioms#2

Merged
hellerve merged 1 commit into
masterfrom
claude/modern-idioms
May 21, 2026
Merged

Update template to modern Carp idioms#2
hellerve merged 1 commit into
masterfrom
claude/modern-idioms

Conversation

@carpentry-agent

Copy link
Copy Markdown

Addresses #1.

  • Module-level docs: added a (doc MyMod ...) block with installation/usage examples, matching the pattern used by carpentry-org packages like strbuf, json, and http.
  • docs-url config: added (Project.config "docs-url" ...) to gendocs.carp so generated docs link back to the repository.
  • File naming guidance: updated README to tell users to rename main.carp to match their module name (e.g. my-mod.carp for MyMod), and to update load paths in gendocs.carp and test/tests.carp accordingly. Also reminds users to set docs-url.

Opened by the carpentry-org heartbeat agent (Claude). Veit has not reviewed this yet.

Add module-level doc to MyMod, add docs-url config to gendocs.carp,
and clarify in README that the main file should be renamed to match
the module name.
@carpentry-agent

Copy link
Copy Markdown
Author

Build & Tests

CI passing on both ubuntu and macOS. No local Carp compiler available on the review host to verify independently.

Findings

  1. Setup instructions in module doc string (main.carp:1-16). The (doc MyMod ...) block mixes API documentation ("is a template module you should replace with your own") with project setup instructions ("Rename this file to match your module name"). Module doc strings end up in generated documentation — a user browsing the docs would see instructions meant for the library author. Consider moving the rename/setup guidance to a comment above the doc form, and keeping the doc string focused on what the module does.

  2. Gratuitous reformatting of greet (main.carp:19). The multi-line if was collapsed to a single line. For a template repo that beginners will read and modify, the multi-line form was arguably clearer. This is minor but it's a change with no upside for the template's purpose.

  3. Good additions. The docs-url config in gendocs.carp, the README guidance on renaming main.carp and updating load paths, and the overall modernization are all useful. The README is noticeably better.

Verdict: merge

The substantive changes (docs-url, README guidance, module docs) are improvements. The style nits above are minor and not blocking.

@hellerve hellerve merged commit 208aa67 into master May 21, 2026
2 checks passed
@hellerve hellerve deleted the claude/modern-idioms branch May 21, 2026 07:44
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