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
I believe we could make this fairly automatic, but I think the library must do this as it is
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 pbristow_at_[hidden]
This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC