On 1/27/26 10:22, Joseph Myers wrote:
On Tue, 27 Jan 2026, Sandra Loosemore wrote:
BTW, having finally finished PR 122243, I have been intending to write up
something for the internals manual that says that all options should either
have documentation or be marked "Undocumented", along with the more specific
documentation conventions re indexing, listing in the option summary, etc. I
don't think this should be controversial.
Preferably undocumented options not marked as such should be detected by
the testsuite (or earlier, causing a build failure); we've done a lot
better at consistency of option --help text after the trailing '.' test
was added to the testsuite. (Though it might be hard to check that e.g. a
target option has documentation for that target rather than another target
with a same-named option.)
Yes, I ran into that problem with the scripts I hacked up for PR122243.
I tried to take extra care to go through all the target-specific options
manually to compensate.
Overall my scripts were useful as an aid to improve the docs, but
definitely not reliable enough for testing purposes. There are still
some options that are "special" and are documented in a different form
than what appears in the .opt files, and a handful that I just gave up
on trying to document (mostly options used only in specs with no
existing description or comments at all).
-Sandra
-Sandra
