I've used doxygen with great results a la doc book. There is a section at the beginning of each file , @file, where you can put the usage examples, general documentation, rationales, etc. Most people think of doxygen as only the tags after each function... With a bit of patch and perl processing, it's used at Bloomberg to generate all the documentation, and it works great (when the documentation is well- written). There can be a few glitches, but the doc always reflects the actual code, and it makes editing the doc so much easier. However when it is unfinished, it is not pretty. That is perhaps the greatest disadvantage. -- Hervé Brönnimann hervebronnimann@mac.com On Mar 9, 2007, at 4:29 AM, Paul A Bristow wrote:
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Gennadiy Rozental Sent: 08 March 2007 20:15 To: boost@lists.boost.org Subject: Re: [boost] Copy editing documentation
"Nava Whiteford" <nwhiteford@tchpc.tcd.ie> wrote in message news:Pine.LNX.4.44.0703081732010.24682-100000@vual.tchpc.tcd.ie...
I'd be interested in hearing your views. As an aside could the class documentation not be generated directly from the source using something like Doxygen?
I personally don't like docs produced using Doxygen (or similar). They still require considerable effort and in most cases look like reference rather than users guide/tutorial.
Strongly agree - OK for reference but using Doxygen usually deludes the programmer that he has done all he needs to - so there is no "How to /How do I ..." content. Most people 'get it' much for quickly from examples - and only occasionally need reference info.
Paul
--- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/ listinfo.cgi/boost