An attribute's `#:` comment does not reach the API reference

[FabianHofmann]

Prompt: "Let's be honest, couldn't we be stricter and just remove these comment for good. would they help you in anycase when scanning the code?", then "Open an issue for the repository-wide change".

Note

The following content was generated by AI.

Description

A #: attribute comment never reaches the API reference. mkdocstrings reads the code through griffe, and griffe ignores #: comments. It reads only a string literal directly below an attribute. The repository has about 500 #: lines, and each one is a source comment only. AGENTS.md allows #: attribute docs as if they were documentation.

Reproduce (checked on the head of #732):

pixi run docs-build
grep -c 'What the file as a whole is' .docs/reference/program/index.html   # 0

src/mathspec/program.py puts that text in a #: line above Program.description. On the page, Program.description, and all four fields of GivenTargets, show a signature with no text.

Decide:

1. Public fields of an exported class (Program, Spec, GivenBlock, …): move the text to an attribute docstring, or to an Attributes: block in the class docstring, so the page shows it. Or drop it.
2. Internal names (module constants, locals, private attributes): remove the #: line.
3. Test fixtures: keep them, or remove them.
4. Change the #: line in AGENTS.md to match.

Related links

• https://mathspec.readthedocs.io/en/latest/reference/program/
• feat(language): a spec is composed from files that each state part of it, and patched with files that each change part of it #732 removes the #: lines on the internal names it adds, and nothing else.