Re: [boost] Improving Documentation

newer
Permission to proceed?

older
[config][release] Release notes...

Andrew Hundt

11 Oct 2013 11 Oct '13

7:42 p.m.

On Fri, Oct 11, 2013 at 2:49 PM, Robert Ramey wrote:

...

Mathias Gaunard wrote:

...
On 11/10/13 15:31, TONGARI J wrote:

...
I think Doxygen is fine for "regular" libraries, but I always have a question: how could a library like Spirit be doucumented with it?

Same as any other library. You document the data types and the functions.

what about the type constraints - aka concepts? and templates?

You can document template parameters with doxygen. If you are using the boost concept check library you can also use those classes to document your concepts. I believe gil does that if you would like an example. You can also always add custom fields fairly easily if none of the existing ones meet you needs. Cheers! Andrew Hundt

Show replies by date

Paul A. Bristow

12 Oct 12 Oct

8:59 a.m.

New subject: Improving Documentation

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Andrew Hundt Sent: Friday, October 11, 2013 8:42 PM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation

On Fri, Oct 11, 2013 at 2:49 PM, Robert Ramey wrote:

...
Mathias Gaunard wrote:

...
On 11/10/13 15:31, TONGARI J wrote:

...
I think Doxygen is fine for "regular" libraries, but I always have a question: how could a library like Spirit be doucumented with it?

Same as any other library. You document the data types and the functions.

what about the type constraints - aka concepts? and templates?

You can document template parameters with doxygen. If you are using the boost concept check

...

you can also use those classes to document your concepts. I believe gil does that if you would

library like an

...

example. You can also always add custom fields fairly easily if none of the existing ones meet you needs.

You can also document \pre and \post conditions - aka 'concepts'. This with \returns \param and \tparam allows one to match the info and style of SGI style documentation (but with hyperlinking). (and there are others like \sa = see also). Paul

Andrey Semashev

9:31 a.m.

New subject: Improving Documentation

On Sat, Oct 12, 2013 at 12:59 PM, Paul A. Bristow wrote:

...

...
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Andrew Hundt Sent: Friday, October 11, 2013 8:42 PM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation

On Fri, Oct 11, 2013 at 2:49 PM, Robert Ramey wrote:

...
Mathias Gaunard wrote:

...
On 11/10/13 15:31, TONGARI J wrote:

...
I think Doxygen is fine for "regular" libraries, but I always have a question: how could a library like Spirit be doucumented with it?

Same as any other library. You document the data types and the functions.

what about the type constraints - aka concepts? and templates?

You can document template parameters with doxygen. If you are using the boost concept check library you can also use those classes to document your concepts. I believe gil does that if you would like an example. You can also always add custom fields fairly easily if none of the existing ones meet you needs.

You can also document \pre and \post conditions - aka 'concepts'.

This with \returns \param and \tparam allows one to match the info and style of SGI style documentation (but with hyperlinking).

(and there are others like \sa = see also).

While I agree with you that Doxygen is a great tool for generating reference sections, when I was writing Boost.Log docs I found that Boost stylesheets discarded most of the special tags (AFAIR, \sa was one of them; \cond doesn't always work, I don't remember the others). This was particularly frustrating because //! style comments for functions would not get into docs (the functions would appear undocumented). Also formatting for some long declarations (e.g. functions with long return/argument types) is not always pretty. These problems sometimes require quite an amount of scaffolding just to make the code look well in the docs, which actually makes the real code more cluttered.

Paul A. Bristow

14 Oct 14 Oct

8:11 a.m.

New subject: Improving Documentation

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Andrey Semashev Sent: Saturday, October 12, 2013 10:31 AM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation

...
(and there are others like \sa = see also).

While I agree with you that Doxygen is a great tool for generating reference sections, when I was writing Boost.Log docs I found that Boost stylesheets discarded most of the special tags (AFAIR, \sa was one of them; \cond doesn't always work, I don't remember the others).

...

This was particularly frustrating because //! style comments for functions would not get into docs (the functions would appear undocumented). Also formatting for some long declarations (e.g. functions with long return/argument types) is not always pretty. These problems sometimes require quite an amount of scaffolding just to make the code look well in the docs, which actually makes

OK - more work now - and all *could* be made to work - we just need to encourage Steven Watanabe or someone to fix the XSTL code that handles them. The Quickbook admonitions work nicely and look just like in Quickbook. the real code more cluttered. But at least the comments are with the code - something that as reader of code I very much like. And it reduces the risk of mismatch between comments and code compared to separate files. Syntax coloring comments in a suitable color (I much prefer green) makes them more or less disappear for me when trying to read the actual code. Can I make a concrete suggestion? That we take an existing library (whose docs we don't like much) and I (and anyone else who wants to contribute) will try to redo the docs using Quickbook/Doxygen for C++ reference section and AutoIndex and try to see how far we can meet people's needs/wishes. I would suggest Units - but it is a bit big. (Boost.Math would be excellent - but it is dauntingly big!) Ideas? Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com

Daniel James

8:46 a.m.

New subject: Improving Documentation

On 14 October 2013 09:11, Paul A. Bristow wrote:

...

...
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Andrey Semashev Sent: Saturday, October 12, 2013 10:31 AM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation

...
(and there are others like \sa = see also).

While I agree with you that Doxygen is a great tool for generating reference sections, when I was writing Boost.Log docs I found that Boost stylesheets discarded most of the special tags (AFAIR, \sa was one of them; \cond doesn't always work, I don't remember the others).

I think if \cond doesn't work then it's probably a doxygen bug. I don't think the things that it hides should be included in the xml that doxygen generates. The latest doxygen appears to have a bug here (it messed up the interprocess adapative_pool documentation), so I had to downgrade to fix the build. I haven't investigated it yet.

...

OK - more work now - and all *could* be made to work - we just need to encourage Steven Watanabe or someone to fix the XSTL code that handles them. The Quickbook admonitions work nicely and look just like in Quickbook.

Some of these tags shouldn't be too hard to support, you just need to look at the doxygen xml file to see what tags are generated, and then work out the boostbook/docbook equivalent. Btw. they're boostbook admonitions, quickbook isn't involved in the doxygen reference documentation (apart from for the asio and geometry documentation).

Robert Ramey

12 Oct 12 Oct

4:55 p.m.

New subject: Improving Documentation

Paul A. Bristow wrote:

...

...
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Andrew Hundt

...

...
You can document template parameters with doxygen. If you are using the boost concept check library you can also use those classes to document your concepts. I believe gil does that if you would like an example. You can also always add custom fields fairly easily if none of the existing ones meet you needs.

You can also document \pre and \post conditions - aka 'concepts'.

To me, pre/post conditions are something entirely different than type requirements.

...

This with \returns \param and \tparam allows one to match the info and style of SGI style documentation (but with hyperlinking).

I did spend some time with this but was unable to get something that worked to my satisfaction. I reluctantly gave up on Doxygen because I felt I would have had to spend a lot of time making another "layer" to handle the stuff I thought was missing. I was reluctant because I thought that Doxygen was on the right path - literate programming - but didn't really support the kind of programming we do here at boost. I believe that this view is supported by the Doxygen documentation we see here. Mostly it seems that it's short version of the header with some live links which point somewhere else - which is totally backwards in my opinion. I don't see how this can really work for templaltes. It's also not much more helpful than just browsing the source code headers - which in many cases I end up having to do anyway. Robert Ramey

4167

Age (days ago)

4170

Last active (days ago)

List overview

Download

5 comments

5 participants

participants (5)

Andrew Hundt
Andrey Semashev
Daniel James
Paul A. Bristow
Robert Ramey