On Tuesday, February 04, 2003 8:19 AM [GMT+1=CET], Jeff Garland <[EMAIL PROTECTED]> wrote:
> > Synopsis has tunable comment processors - you can make them as > > smart or as > > dumb as you want them to be (it's Python, so it's easy ;-)). In my > > case, > > the rule is simple - the comment describing the function appears as > > a solid > > block right before its declaration with no intervening line > > separation. > > Sorry I think I was unclear. I'm asking how a portion of that block > is devoted to a specific portion of the description. For example: > > /** Brief description of function. > Long description of function > .... > @return Describe the return value here. > @pre precondition for the function > @post postcondition for the function > */ > int f(); Nay, it was I who was unclear. How you do that is tunable. If you like that style, you can use it. Personally, I would do something like this: // Brief description of function // Long description of function // ... // // Returns: Describe the return value here. // Preconditions: precondition for the function // Postconditions: postcondition for the function // Throws: what it throws // ... Because I want my comments to look like English ;-) > > > That's good to hear. It doesn't look like Synopsis has an > > > XML ouptput formatter yet -- is that in the works? > > > > It has a DocBook formatter, in fact... though it's being a little > > bit > > strange about type qualifiers at the moment. We just need to take > > a look at > > the differences with the HTML formatter to see what the major > > differences > > are. > > Sounds like it's on the right track. Yep. > > > Also, as I recall > > > last time I checked on Synopsis I had installation issues or some > > > other difficulty -- that would have been shortly after the last > > > committee meeting. > > > > I think I can help with that. Anyway, since I've just wiped my > > machine I'm > > going to want to reinstall it myself, so we can experience the joys > > together ;-) > > You first ;-) Okey doke. > > > Agreed, but I think in this case the diversity might be ok. > > > Document generation is sufficiently complex that I'm sure that > > > Synopsis and Doxygen will continue to have various strengths and > > > weaknesses that might draw some users to one or the other > > > solution. > > > > They might, but as Doug has pointed out repeatedly, you won't be > > able to > > simply process regular C++ code and get reasonable BoostBook, so > > we'll have > > to add some new directives, markup formats, etc. That will be > > repeated work > > for us, on top of whatever differences the two tools have. > > Well, you can get plenty of output from regular C++ but if you don't > write > comments in the code in a structured way no solution is going to > generate > a reference materials from the code, period. Clearly. > Either solution can > generate > an unannotated header synopsis from pure C++, but that isn't going to > cut > it for boost references. OTH, some people might want to take > unannotated > source, generate a skeleton set of reference docs in XML from the > source, > add meat to the generated XML and just maintain the XML. > > As for repeated work, I don't think I follow. Doug has already > written most > of the translation scripts for Doxygen XML output to BoostBook XML. > For > Synopsis you could write a backend that just outputs BoostBook > directly. > Or you could just use the Docbook directly and live with a slight > reduction > in functionality. Anyway, once it is in BoostBook all the backend > processing is the same so I don't see that there is much overlapping > work... It's the front-end processing needed to make extracting usable BoostBook from C++ source with minimal annotation that I think will be repeated. Dave Abrahams Boost Consulting http://www.boost-consulting.com ------------------------------------------------------- This SF.NET email is sponsored by: SourceForge Enterprise Edition + IBM + LinuxWorld = Something 2 See! http://www.vasoftware.com _______________________________________________ Boost-docs mailing list [EMAIL PROTECTED] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
