Re: [boost] Improving Documentation

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Mateusz Loskot Sent: Tuesday, October 15, 2013 12:19 AM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation

On 14 October 2013 18:39, Paul A. Bristow wrote:

...

...

From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Mathias Gaunard On 12/10/13 19:59, Eric Niebler wrote:

...

I've also been frustrated by the poor support for concepts in our documentation toolchain. "Just write your docs in Boostbook XML" is like telling people to program in assembly -- if assembly were extremely verbose.

Maybe Quickbook could be extended to be able to output the required XML for concepts?

What is required that is not already provided by Doxygen comments of type

\tparam \param \pre \post \returns etc?

If we have a concept like

template <class T> struct DefaultConstructable;

It will be possible to get a link to this from \tparam description

\tparam The type of the elements stored in the circular_buffer. T has to be DefaultConstructible.

---

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This sentence should not even appear there, but something like:

\tparam The type of the elements stored in the circular_buffer. \modelof DefaultConstructible

and that's important point of the whole debate, IMHO.

It is about marking, extracting, formatting, synthesizing and interlinking all of the animals in

If I have a concept EasilyDocumentable, how shall I stuff Doxygen with data to get page like

OK - modelof would be nice but: 1 We could get \modelof added to Doxygen. 2 The key information DefaultConstructible is present - a big improvement on the current situation. And if you go to the source hpp, you will also find the comment with this info. the C++ vocabulary: I have a long term vision of starting with Clang and adding the documenting-from-comments features, but we are way off that. A GSoC project? We also perhaps don't want to put a lot of work into making BOOST_CONCEPTS work automatically, only to find that it obsolete if concepts are added to C++. For a year or several, we should be using the tools we have to best. this?

http://www.boost.org/doc/libs/1_54_0/libs/utility/CopyConstructible.html

If you wish I could tackle this now - but I'm too busy with a bout of industrial strength DIY at present ;-) But when I'm free, is this worth tackling?

If I have a model well_documented, how...like this?

http://www.boost.org/doc/libs/1_54_0/libs/fusion/doc/html/fusion/container/v...

with "model of" list of corresponding concepts, valid expressions and semantics would be nice too.

It's OK - but it's very much reference info - it doesn't have hyperlinks to explain much - not even links to the source files! As an test example, it's also a bit of a googly because Fusion a bit of a weird and wonderful meta-language-ish beast. Another test-case example? Cheers. Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com