[cfe-dev] scan-build man page
James K. Lowden
jklowden at schemamania.org
Thu May 10 15:29:37 PDT 2012
On Thu, 10 May 2012 12:10:24 -0700
Ted Kremenek <kremenek at apple.com> wrote:
> If the list of checkers can be easily verified with sed or perl, why
> can't this section of the man page (if we want to include it) be
> auto-generated? It's just the reverse process.
Because you don't want markup in Options.td.
It's easy to use regex to find the markup and extract the data. It's
impossible to devise an algorithm that can generate the markup
spontaneously except insofar as the markup is derivable from something
about the data (say, its structure).
Here's an example from the page:
Check for sending 'retain', 'release', or 'autorelease' directly to a
That's a little broken, a first-draft cheat. Those single quotes
shouldn't be there because groff can't style them as open-close
quotes. In fact, IIUC they're literals, which in PDF format won't have
quotes at all! (Question for the audience: would the programmer adding
this to Options.td know that?)
What you want is
Check for sending
.Li retain ,
.Li release ,
directly to a Class
That's not the only such example.
Do you want to keep text just like that -- verbatim, no whitespace
before the line ending -- in Options.td? Clearly not. Do you want to
invent/use some other markup that can stand in for it, and write a
translator to produce the appropriate mdoc markup? When the mdoc
output is wrong, how much debugging do you want to do? When the
invented markup is insufficient, how much more time do you want to pour
If you care about the documentation enough to write it, how much time
do you want to invest learn the clang NIH markup toolchain?
Remember, these questions exist in the service of only one question:
how to generate documentation programmatically? If the question is
shortened to "how to generate documentation", the answer is easy:
Typing! And the problem of verification is reduced to a tiny shell
More information about the cfe-dev