[boost] Synopsis Thoughts (was Re: Reference documentation)

From: William E. Kempf (wekempf_at_[hidden])
Date: 2002-10-30 17:57:11

I've been looking at Synopsis.  First, I have to qualify that I've been
looking only at the documentation and examples and have not installed or
used the tool myself yet.  But I'd still like to make some observations.

The design of Synopsis is promising.  The modular design allows you to
modify the transformations in just about any way.  (How easy it is to
actually code this stuff I don't know, as I've not looked at the source.)

The current C++ parser seems to be well up to the task, unlike other tools
of this ilk that I've used in the past.  (This is based on the output for
Boost.Python, which captured details that would have choked the other
tools I've used in the past.  To be fair to Doxygen, the last time I used
it was over a year ago, so maybe the parser has improved.)

The fact that you are not limited to any specific comment style is
important to me.  Most other tools limit you to JavaDoc style comments
(i.e. content, not structure), and the JavaDoc tags don't cover all of the
things I'd want documented.  For instance, rationale.

The HTML output is OK, but I personally dislike this JavaDoc format using
frames.  Also, this format is ONLY useful for reference documentation. 
Boost documentation goes well beyond just reference material, which is
where a lot of tools like this start to fail.  If Synopsis produced
DocBook output, however, this wouldn't be an issue since the rest of the
documentation could be written in straight DocBook XML/SGML files with
entity references to the Synopsis produced reference documentation.

There's still to other issues with generators like this.  One is the
intrusiveness of comments.  This may not be as big of an issue with
Synopsis, since the comments can be in any format, and thus you have more
chance of keeping the code "clean" from a lot of markup that makes it hard
to decipher the actual code.  What's not clear is if Synopsis can handle
the comments in the source files instead of the header files, which would
help even more.

The other issue is with whether or not code generation is even possible
(let alone useful) for some code, since it will pick up implementation
details and may fail to capture the actual interface because of these
details.  I see no way to override what Synopsis sees in this regard, as
you can do with other tools.  But even in these cases, it might be useful
to use Synopsis to produce an initial "template" on which developers can
then hand write the actual documentation.  If the documentation produced
were in DocBook we could even write other tools that would check this hand
written documentation against the actual code to report discrepancies
(which would be evaluated by a person for true errors, of course).

-- 
William E. Kempf