[cfe-dev] scan-build man page

[Ted Kremenek]

On May 10, 2012, at 11:32 AM, "James K. Lowden" <jklowden at schemamania.org> wrote:

>> The last thing I want to do is every time I roll a new
>> checker build that I need to manually check if the list of checkers
>> in the man page is up-to-date.
> 
> OK, but that's orthogonal to how the documentation is
> maintained.  Better to check the documentation than to generate it.  
> 
> First, let's not exaggerate.  If there are N checkers and you add one,
> you have to check the man page for 1, not N.  At release time, the
> primary focus should be not counting checkers, but ensuring that the
> documentation is coherent and accurate.  No machine can do that.

Completely agreed.

>  
> 
> Second, you will find, in practice, that editing the man page
> "manually" is in fact easier and produces better results. Why?  Checker
> descriptions require markup.  Markup is a domain of knowledge. The
> people who know that domain best are not necessarily the ones adding
> the checkers.  Requiring markup in some tiny doc-fragment in Options.td
> -- which itself uses *other* markup -- by someone who doesn't know or
> care about markup is a recipe for inconsistency and error.  Requiring
> the person taking care of the man page to grovel around in some other
> file is a good way to encourage him to find something better to do with
> his time.  

That's an interesting argument that I'll need more time to digest.  I'd really like to have a more cohesive documentation story for the analyzer, but I'm not certain what it should be.  This discussion speaks more about the command line usage of scan-build, which is limited in scope.  Assuming we get beyond this current thread, I assume we will find some resolution here.  My broader concern is about the documentation of the checkers themselves.  Right now it's hardly anything, but where should it eventually go?  My interpretation of your points is that pointing some kind of crazy markup in Options.td is a recipe for failure (e.g., creating a meta-documentation with markup that can then be lowered to something else).  I can see that argument, as that is something else for someone to understand and maintain.  The main conclusion I can draw from that then is that we should have one canonical way of providing documentation for the checkers, and if we had to pick one location for that it would probably be the web, not a man page.

> 
> Third and last, to verify that the checker list and the documentation
> are in sync doesn't require the documentation be generated.  It requires
> only that they be verified.  If TableGen (or whatever) produced a simple
> ASCII list of checkers, a tiny shell script could scrape through the
> man page to make sure they're all present and accounted for.  Here,
> let me help:
> 
> $ sed -ne '/Sh..*CHECKER/,$p' scan-build.1 \
> 	| awk  '/^\.It/ {print$2}'
> core.AdjustedReturnValue
> core.AttributeNonNull
> core.CallAndMessage
> core.DivideZero
> core.NullDereference
> core.StackAddressEscape
> core.UndefinedBinaryOperatorResult
> core.VLASize
> core.builtin.BuiltinFunctions
> core.builtin.NoReturnFunctions
> ....
> 
> Let me know when TableGen is ready.  

I both agree and disagree with you.  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.  There's not really any special markup here either.  The names of the checkers are in bold, and everything else is not.  This seems like a case of piping the output of scan-build through a perl script that generates that markup for man.

I understand completely if this isn't something you wanted to tackle.  You just wanted a man page.  As a first cut I think what you have is fine.  I'm sorry I dragged you into a broader discussion which had to do with my own musings of where I think this should go.  I will go ahead and commit the man page you added.  Thanks so much for providing it.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20120510/2dbafd51/attachment.html>