[cfe-dev] [PATCH] LibTooling docs

[James K. Lowden]

On Sat, 21 Apr 2012 14:28:03 +0100
David Röthlisberger <david at rothlis.net> wrote:

> b. The generated document should be checked into source control so
> that if someone changes ClangCheck.cpp they notice the effect on the
> documentation in their diffs. 

I see where you're going, but that's not the way.  The changes might
not be meaningful to the documentation, and check-in time is not
*necesarily* the best time to update it.  (I could argue the best time
is before the code is changed, for example, or that documentation is
best handled by someone better acquainted with English.)  

You want to know that a given piece of code is documented somewhere,
because changes might invalidate the documentation.  That is the
information you need to keep!  

To verify that source and document match, it is enough to know
the filename, line numbers (or function name), and revision of quoted
source in the documentation.  It could be embedded in the document or in
separate file.  With a bit of sed(1) the quoted lines can be compared
to *any* other revision in the repository, at any time.  

That said, having read and written some documentation, I'm
skeptical of how useful such a system would be.  Documentation is
not "testable" because 

1.  not that much compilable code finds its way into the documentation,
and 
2.  in 2012 semantics cannot be asserted, much less verified.  

After all all, documentation is mostly about how to use something, be
it a class, function, or utility.  Restating the implementation isn't
useful or desirable.  But, yes, examples need to be checked somehow.  

> a. The document generation should be run as part of every normal
> "make all" compilation.

For every release there are many compilations.  Why burden each one 
with extraneous concerns?  No mechanical means can verify that the
document is correct or even meaningful.  Therefore the process of
making it correct falls to humans, just as testing and release
engineering do.  

Good documentation can't be forced or enforced.  It's the
product of conscientious work, nothing more and nothing less.  

--jkl