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

From: Larry Evans (jcampbell3_at_[hidden])
Date: 2002-10-30 19:28:51

William E. Kempf wrote:
[snip]
 > 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

What about just "commenting" the code with a reference to another file
(i.e. like an html "external" hyperlink) which contains any amount of
documentation required.  This way, changing or updating the
documentation would not cause a recompile of the source.  Of course
one might say that this makes it harder to keep the two consistent,
but not by much.  Everybody can have two editing windows open at once.
One could adopt some convention, e.g. function x::y::z(t1,t2,t3) could
be documented in x__y__z_t1_t2_t3.xml.

 > 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

This "template" could produce the "external hyperlink" mentioned above.