Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2013-10-12 12:48:16

Mathias Gaunard wrote:
> On 11/10/13 20:49, 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?
>
> What about them?
> No problem with any of those.

I spent a fair amount of time investigating Doxygen/Quickbook for
these purpose and concluded that making them work would be more
trouble than just filling in XML "forms" to get what I wanted.

> Concepts being entities outside of the source code, you don't use
> Doxygen to define them.

Actually - type requirements on templates - aka concepts - would be
natural match for something like Doxygen.  Basically one would add
the Doxygen markup to the concept checking classes in the Boost
Concept Checking library to include explanation and requirements
on the template parameters.  Alas, I couldn't figure out how to make
Doxgen generate output for templates in a form that I liked.

> The definition of the concept has to be
> written  in Boostbook.

That's what I now do.  I use an XML editor which understands the
BoostBook/DocBook DTD along with some XML templates I
ginned up for Concepts, Types, Functions, etc.

> You can then reference your concept in Doxygen in the documentation
> of a function (template or not), or from Quickbook.

I realize this.  It sounds like you're agreeing with me that 
Doxygen/Quickbook
are not good tools for generating this (essential, for me) aspect of the
reference documentation.

Robert Ramey