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
library

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

https://dl.dropboxusercontent.com/u/43940943/safe_numerics/libs/safe_numerics/doc/html/index.html

and as a single pdf file

https://dl.dropboxusercontent.com/u/43940943/safe_numerics/libs/safe_numerics/doc/safe_numerics.pdf

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
copyconstructable.

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

 http://www.sgi.com/tech/stl/Assignable.html

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

 https://dl.dropboxusercontent.com/u/43940943/safe_numerics/boost/safe_numerics/concept/numeric.hpp

provided).

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

https://dl.dropboxusercontent.com/u/43940943/safe_numerics/libs/safe_numerics/doc/html/numeric.html

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

http://htmlpreview.github.io/?https://raw.github.com/robertramey/safe_numerics/master/safe_numerics/
doc/html/index.html

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

https://dl.dropboxusercontent.com/u/43940943/safe_numerics/libs/safe_numerics/doc/html/index/s10.htm
l

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

https://dl.dropboxusercontent.com/u/43940943/safe_numerics/libs/safe_numerics/doc/html/boost/numeric
/safe_compare/greater_than_equal.html

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
attractive.

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':

https://dl.dropboxusercontent.com/u/43940943/safe_numerics/libs/safe_numerics/doc/html/boost/numeric
/safe.html

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

http://www.boost.org/doc/libs/1_55_0/libs/gil/doc/html/g_i_l_0286.html

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

Views welcome.

Paul

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

https://dl.dropboxusercontent.com/u/43940943/circular_buffer/libs/circular_buffer/doc/html/index.htm
l

showing the info about circular buffer, for example at

https://dl.dropboxusercontent.com/u/43940943/circular_buffer/libs/circular_buffer/doc/html/boost/cir
cular_buffer.html

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]