Macaulay2 / Macaulay2/M2

Document that option names in packages must be exported

Open
#4,508 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bugs directory Documentation
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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.