Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Specify module index descriptions using an attribute rather than a comment #25814

Open
bradcray opened this issue Aug 26, 2024 · 1 comment
Open

Comments

@bradcray
Copy link
Member

bradcray commented Aug 26, 2024

Currently, the descriptions of the modules that appear in the module index document are generated by convention using the first line of the multi-line comment that precedes the module declaration. As noted in #25667, this is sufficiently subtle and fragile that we've sometimes ended up picking up comments that were not designed or intended for that purpose, such as the file's copyright, the first line of a multi-line comment that wasn't intended for the module index, etc.

This issue requests that, now that we have attributes, we update the process of generating the module index to use a special attribute like:

@chpldoc.modIdxDesc("This is the description for my module")
module MyModule { … }

(where I have no attachment to this particular spelling of the attribute's name.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants
@bradcray @dseynhae and others