Add convention for *module* comments
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 3.1k
- Forks
- 264
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 16
Description
SANY supports pre-comments for definitions and declarations—that is, its AST includes the comment immediately preceding a definition or declaration. However, many standard and community modules include a module header that SANY sometimes interprets as the pre-comment of the first definition or declaration rather than as a comment on the module itself.
I propose establishing a convention for the placement and formatting of module-level comments so that SANY can reliably associate them with the ModuleNode.
Contributor guide
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
Compare the module headers in StandardModules/Naturals.tla and CommunityModules/modules/Folds.tla with how SANY associates pre-comments to definitions and declarations. Start by examining the ModuleNode comment handling, then determine a placement and formatting convention that reliably distinguishes module comments from the first declaration's comment. Done means the convention is agreed and documented.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100