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

From: William E. Kempf (wekempf_at_[hidden])
Date: 2002-10-31 09:29:23

David Abrahams said:
> "William E. Kempf" <wekempf_at_[hidden]> writes:
>> 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.

Makes perfect sense, since a good generator (which Synopsis does appear to
be) should make it easy to change the end result.

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

Then the documentation needs updating. :)  But that's good news.

>> 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 only question is how Synopsis attaches the comments to the AST.  But
of course, this is something that should be fixable by the Synopsis
authors if it doesn't already behave that way.

>> 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 can think of several solutions, not all of which would be direct support
by Synopsis (for example, DocBook transformations to remove the unwanted
documentation).  The only concern is the amount of development time (by
Boost or Synopsis developers) required to get the tool to do what we want.

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

Agreed, I'm only concerned with the amount of effort required to do this.

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

Why?  Since Synopsis should be able to produce a full DocBook XML file it
should be fairly trivial to parse both files and produce comparison
results.  For that matter, if the AST file from Synopsis is easily parsed
(one would assume it would be) you could take that route instead.

This may not be needed in the long run, but it doesn't sound to terrible
to do and could turn out to be something useful.

-- 
William E. Kempf