Re: Sphinx integration
"Paul A. Bristow" <[email protected]>
| Newsgroups | gmane.comp.lib.boost.documentation |
|---|---|
| Message-ID | <[email protected]> |
> -----Original Message----- > From: [email protected] [mailto:[email protected]] On Behalf Of > Dave Abrahams > Sent: Wednesday, October 05, 2011 5:26 PM > To: [email protected] > Subject: Re: [Boost-docs] Sphinx integration > > I'm not so sure. The universe of design options is so vast that I think users need to be presented with > alternatives. I find http://cpp-next.com far easier to read than most of the Boost pages, for example. I like that too, but I fear we are not discussing the most important thing. This is focussing on style : I'm worrying about *detailed content* - and what is I believe is often missing from many Boost docs. For me, the really important issue problem is how and where to document what class, functions, etc do, pre and post conditions, 'concepts' and results, returns and side effects, and what it does if you provide bad input - throw or error code or?. You can get off to a good start with good choices of names, but if you have function 'flip', then somewhere you need to document "Swaps the byte order". And there are all the other items as well. "return result;" doesn't help the user much! *No automated tool is going to write all this for you*. So we have two choices. You provide separate text, perhaps in text and/or tables, separately. But for any non-trivial library, you need a tool to organise this, and this means some 'mark-up' system. And keeping the docs in step with the code is more difficult. Or you put the documentation in with the C++ code as comments with some 'mark-up'. This is all the Doxygen conventions do - and they could be processes by other tools too, best of all by an add-in to the compiler. This clutters the code, but syntax color makes this a non-problem for me. (You are reading this in color and not B&W ;-) I've only used Doxygen and I think it can be made to work well enough. Are there other tools that could help us more? Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 [email protected]