Document that option names in packages must be exported
Nobody has claimed this yet.
- Dominant language
- Macaulay2
- Stars
- 435
- Forks
- 297
- Avg merge
- 4d 20h
- Merged PRs (30d)
- 11
Description
This issue was triaged from bugs/dan/0-doc-option-names-in-packages, one of the 857 files removed from the pre-GitHub bugs/ tree by d2c8d27826 and catalogued in #36. The commentary below was written by Claude (Claude Opus 5, via Claude Code), not by @d-torrance, whose account posted it -- please weigh it accordingly.
The original file, verbatim
Document that names of options in packages should be exported
Perhaps improve the error message, too, which comes when the documentation is processed.
Where it stands today
Verified, and the file misplaces the error, which is worth correcting on the way in.
The behaviour
A package-defined option name must be exported, or installing the package fails:
error: mutable unexported unset symbol(s) in package MyPkg: 'MyOpt'
Exporting it installs cleanly. This is undocumented — neither Macaulay2Doc nor the wiki style guide
mentions the requirement, which is what the file asks to fix.
Where the error actually comes from
The file says the message "comes when the documentation is processed". It does not: it is raised from
package closing (Core/packages.m2:511-513, from endPackage), and it fires with no documentation
node present at all. That matters for the documentation being requested — the rule is about the
package's own symbols, not about documenting them — and it also means the error arrives before any
beginDocumentation work, which is why a package author sees it as a load failure rather than a doc
failure.
Notes for whoever picks this up
Two separable pieces: document the requirement (the natural home is alongside export and the
optional-argument documentation template), and improve the message, which currently names the symbol
but not the reason a package author should care — that an unexported option name cannot be written to
the documentation database.
open · disposition issue · source of truth: bug-triage/catalog.tsv
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading Core/packages.m2:511-513 and the documentation covering export and optional arguments. Confirm the package-closing error is independent of documentation processing, then document the requirement that package option names be exported and clarify the error message's relevance to the documentation database.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100