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

From: David Abrahams (dave_at_[hidden])
Date: 2002-10-30 23:12:21

"William E. Kempf" <wekempf_at_[hidden]> writes:

> 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.)

It's written in Python, and it's well-structured. That pretty much
says it all.

> 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.  

Me too, at least in part. However, those kinds of back-end issues are
easily addressed. Stephen and I are working on more-substantive issues
of presentation (e.g. how do you represent a metafunction so it makes
sense?) first.

> 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

It does.

> 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.  

Yes, that's why I like it.

> 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.

I don't see why there would be a problem. From the POV of a C++
compiler, there's no difference between source and header files.

> 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.  

Stephen and I have been talking about ways to eliminate those details
for user documentation, while showing them for implementation
documentation. For example, Boost.Python uses some intermediate
classes in its hierarchy which should be "compressed away".

> 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.  

Synopsis produces an AST, and then interprets it. The basic structure
needed to do any of this should be in there.

> 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).

Hmm, interesting thought. Scary, too, though.

-- 
                    David Abrahams
dave_at_[hidden] * http://www.boost-consulting.com