Re: [Boost-docs] [boost] Improving Documentation

Subject: Re: [Boost-docs] [boost] Improving Documentation
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2013-11-22 17:14:55

> -----Original Message-----
> From: Boost-docs [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of Paul A. Bristow
> Sent: Wednesday, November 20, 2013 12:09 PM
> To: Discussion of Boost Documentation
> Subject: [Boost-docs] FW: [boost] Improving Documentation

I've had yet another go at Robert Ramey's challenge to document his to-be-proposed Safe Integers

You can see the results of my most recent efforts (now only for users) at

and as a single pdf file

Apart from the effort involved in providing Doxygen comments (which I believe is small, especially
during writing the code, because there is lots of boiler plating possible), our main differences of
view are on how to provide the 'concepts' information.

The only true concepts used by this library (at present) are the ubiquitous assignable and

For the more common concepts, I have used a simple link to the concept like

because the library is not using Boost.Concept (yet).

(There is also a concept of a Numeric type but this is not enforced by the use of the library,
although it can be tested using file


The information on type Numeric in this file is documented in my Doxygenated version here:

Robert has contrasted his presentation of concepts (and other information) thus

with mine. I believe that it contains the same information (about Numeric) and can be found by
using the automatically produced Index - see

The other information about operators can also be found using the index, for example, operator>= see

The difference is that Robert provides a simple list, whereas I provide an index to individual
operators (not all are currently documented - retrofitting is tedious!).

IMO the user will find the index method easier (when that is the users' expectation). With a tiny
library like this (chosen as a demo because it is small) it may be easy to find the concepts
section, but for a typical much larger library making the table and finding it will be less

The size of the documentation is much, much bigger, but it is more likely to be complete, and more
likely to be accurate, (and nearly all will be unread so its repetitions unimportant).

A typical example of what the user is likely to read is about the key template 'safe':

You will note how this references concepts DefaultConstructible,...

If Concepts get into the C++ language, or Boost.Concept is used, or the method using by Boost.GIL
- see

I believe we could make this fairly automatic, but I think the library must do this as it is

Views welcome.


PS A more typical library with Doxygen comments in the C++ reference section is at

showing the info about circular buffer, for example at

Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
+44 1539 561830  07714330204

This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC