Douglas Gregor <[EMAIL PROTECTED]> writes:
> On Saturday 16 November 2002 07:20 pm, Stephen Davies wrote:
>> On Sun, 2002-11-17 at 05:39, Douglas Gregor wrote:
>> > (g) Autogeneration from Synopsis, Doxygen, etc. (Difficulty: 3?)
>> > C++XML could be automatically generated from any tool that extracts
>> > documentation from C++ code. The task is to write a documentation backend
>> > for some of these tools so that Boost developers can write documentation
>> > in the source and still use the same back-end formatting that other
>> > developers use.
>>
>> I think the largest difficulty here is the disparity between the level
>> of source code and the abstraction of your documentation.
>>
>> For example, the function documentation lists everything as being in
>> function.hpp. You have gotten rid of most of the templates and turned
>> one of them into templateN with arguments up to N and a '...'. All the
>> member functions have been renamed to fooN().
>
> I don't really expect any documentation abstract tool to deal with the
> Function headers without serious help, and I'm fine with that. I think we
> should concentrate on getting the "normal" cases working, where libraries are
> actually written the same way they are supposed to be used (what a concept!).
I'm not sure that actually occurs, does it? I'm serious: some degree
of "folding" always seems to occur between the published interface and
the actual implementation.
>> And finally there is the issue of where to put the
>> comments. Currently Synopsis doesn't support writing comments in a
>> separate document, but it wouldn't be too hard to add that
>> feature. But how much do you want Synopsis to do? Generating the
>> XML should be easy, as long as it is standalone - Synopsis
>> currently has no XML support so things like "insert the
>> documentation into the header tag" is not so easy to do. Writing
>> the XML into a separate document is fine, you just traverse the
>> Abstract Syntax Tree, printing out some text for each node.
>
> With the C++ XML format, the comments are mingled with the C++
> constructs. For instance, a <header> tag can contain paragraphs and
> sections with any DocBook markup in it, there are short description
> tags (<purpose>) and long description tags (<description>) for
> classes that can be filled with DocBook markup, etc.
>
> However, I wouldn't expect non-reference documentation to ever be
> seen by Synopsis. It would likely be written into a different
> DocBook-ish XML file
...or, say, ReStructuredText...
> that would be merged before the C++XML XSLT stylesheets are applied,
> so that entities named in the non-reference document via, e.g.,
> <classname> can point to the appropriate entities.
--
David Abrahams
[EMAIL PROTECTED] * http://www.boost-consulting.com
Boost support, enhancements, training, and commercial distribution
-------------------------------------------------------
This sf.net email is sponsored by: To learn the basics of securing
your web site with SSL, click here to get a FREE TRIAL of a Thawte
Server Certificate: http://www.gothawte.com/rd524.html
_______________________________________________
Boost-docs mailing list
[EMAIL PROTECTED]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
