-----Original Message----- From: Boost-docs [mailto:boost-docs-bounces@lists.boost.org] 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_numeric... and as a single pdf file https://dl.dropboxusercontent.com/u/43940943/safe_numerics/libs/safe_numeric... 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_numeri... 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_numeric... Robert has contrasted his presentation of concepts (and other information) thus http://htmlpreview.github.io/?https://raw.github.com/robertramey/safe_numeri... 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_numeric... 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_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_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_b... l showing the info about circular buffer, for example at https://dl.dropboxusercontent.com/u/43940943/circular_buffer/libs/circular_b... cular_buffer.html --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com