[cfe-dev] scan-build man page

[Joerg Sonnenberger]

On Thu, May 10, 2012 at 11:35:32AM -0700, Ted Kremenek wrote:
> > One of the things I hate about git is that the user interface is
> > inconsistent enough that they have to create a hundred man pages
> > documenting the different option sets.
> 
> That's fair, but would you agree that the idea is good in principle, and that
> this is problem with the execution, or do you think the fundamental
> design of that help system is flawed?

Personally, I find it slightly annoying since by default that will put
me in some pager.

> > 
> > I really, really hope scan-build won't end up with that mistake.
> 
> Just to be clear, which mistake are you referring to? 
> The inconsistency of the interface?

Having hundreds of different switches that need to be explained. This is
different from having a hundred checkers available, since they all
follow the same style.

> scan-build's documentation, which can be found by running it with
> no options, consists of a short list of options, a list of checkers,
> and a short example (at the very end).
> The man page that James provided is essentially this output reformatted
> as man page.  Other documentation can be found on the
> clang-analyzer.llvm.org website, that has a bunch of information such
> as tips for using it with projects the use configure, etc.  All of that
> is missing from the help emitted from the tool.

scan-build without arguments can default to the equivalent of --help.
I'm not sure about including an example in that, but that's a separate
point.

> Given your feedback, would you think a scan-build be to have a very
> focused man page that omitted the checker descriptions?  That would
> essentially be NAME, SYNOPSIS, OPTIONS, and EXAMPLE.  I could then
> see 'scan-build help' just loading up the man page, and providing
> other means to get the list of checkers.

I would include the "normal" checkers, e.g. those that are stable and of
interest for a wide audience.

> > Now the real question in all of this is how much of the options are
> > really scan-build specific and not shared e.g. with clang. For complex
> > build systems it can be a lot easier to integrated clang --analyze
> > directly and the checker specification and many other things are
> > logically more a part of the clang CLI.
> 
> It was never my intention to make 'clang --analyze' a public part of
> the interface to the analyzer, but more a low-level implementation
> detail.  The problem with people adopting clang --analyze directly is
> that it encumbers us with how we (one day) will design global analysis.
> My hope was to have a simple command for "analyzing my project or
> source file", and that was meant to be scan-build, or have proper
> integration within an IDE that understands that 'clang --analyze' is
> just one implementation detail part of probably others that need to be
> considered when integrating the analyzer into an IDE.

My problem with scan-build is that it requires at least Perl. NetBSD has
a mostly self-contained toolchain, so that's problematic.

Joerg