Documentation


Documentation of software libraries and APIs has a well deserved reputation for being obtuse, opaque, incomplete, hard to use and not very helpful. Boost documentation is better, but still not good enough. One of the main motivations of this website is to improve documentation of libraries submitted to Boost.

Structure

A library MUST contain a doc/html directory with an included file index.html. The documentation should be browsable with or without being connected to the net.

Optionally, it may include Information to build the HTML directory from other tools such DocBook, BoostBook or QuickBook or some other system. These systems provide the benefit of being able to generate output formats other than HTML such as PDF, ebook and others.

Contents

What should documentation for a software library contain? The answer turns out to be surprisingly un obvious.

The obvious thing seems to just write expanded information about each class and function. However, it's very difficult to keep this from ending up just paraphrasing the code. Documentation which is prepared separately is much more likely to manifest "conceptual integrity". That is, it is likely to look like a set of minimally coupled, composable orthogonal ideas whose purpose and usage is easy to understand. Generating or writing documentation from the completed code is more likely to result in a library that looks like a collection of dependent components which are harder to understand and use. For this reason, I advocate building the documentation concurrently with the code rather than waiting for the code to be written and tested.

Documentation of types and functions is essential. But it doesn't address the documentation of template classes and functions. A template is a group of classes or functions rather than just one of these. So all the information which is fixed for a class or function such as arguments can't be specified.. This problem has been addressed by the adoption of concepts and concept checking classes. Just as function type signatures specify the types a function takes as arguments, concepts specify which types can be used as template arguments. The word concept is very confusing. A better term would be type requirements but concept is the historically accepted term so we'll continue to use it here. Here is more information helpful for writing documentation using concepts:

  • How to use the STL documentation This the key document which describes how to write documentation for C++ library which might contain templates. The STL website is the original source for the STL library and hence contains of how the above description is used.

  • Fusion I found this Boost library to be the single most helpful example of how to write good documentation.

    • It's a real example - not an explanation of how to do it

    • It's a very large library with many facets. But the documentation is very regular in that the same patterns described above are used throughout. Once you get how it works for one part of the library the rest of it very familiar. If you use Fusion you'll spend hours (or days) pouring over this documentation. But you'll never feel that you're lost - just awed inspired.

  • Writing Documentation for Boost

    This is what the boost website says about documentation. It seems well written, and it's not really inconsistent with the above, but by itself, it wasn't enough for me to get me on the right track.

I've attempted to synthesize information from the above sources into the following "templates" which a library author can "fill in". One can include these templates in his library documentation, eliminate those section which are not applicable, and fill in the information particular to his component.

Here is an outline of what library documentation should look like. Not all libraries need all the sections, but most should be there. Links point to "mock ups" for the corresponding section which can be used as a basis of creating your own documentation.

  • Introduction

    A concise description of what the library does. The object is to give the reader enough information to know whether this library addresses the need which lead him to check this documentation in the first place. Often times, a short motivating example can show what "problem" the library solves and how it is used to do it.

  • Tutorial

    Detailed examples of library usage. These examples should include code that the user can build and try on his own.

  • Notes

    Include useful formation which doesn't fit anywhere else. Examples would be:

    • Pointers to other libraries which do a similar thing.

    • Information on testing.

    • compiler/platform quirks and dependencies.

  • Concepts

    List of concepts defined by the library.

    Each concept is a description of a set of operations that a type must support in order to be considered as meeting the requirements of the concept. The concept name is a succinct way of specifying the constraints on type parameters passed to C++ templates. Note that you need document only the new concepts you create. Those that are included from the Boost Concept Check headers are already documented.

  • Types

    List of C++ types defined by the library.

    A type used by the library. A type may be a C++ template, class or structure. If it is a template, there are no type parameters so that section can be dropped. If its a class, member functions will be documented in the section "New Valid Expressions". This is somewhat different than the traditional way of documenting class member functions and types. The advantage is that is more compatible with the documentation of template types. In any case, the actual class header is available for reference.

  • Functions

    List of non-member functions and function templates.

    C++ functions and function templates can be documented the same way. The only difference is that for functions, the type requirement section can be deleted.

  • Rationale

    While working on your library, keep a list of reasons for the design decisions you made. Include that list here.

  • Change Log

  • Acknowledgements

  • References

Note the strong similarity in the documentation for Concept and Type.

The above Outline for a simple library with a smaller number of concepts, types and functions. For a example where the number is much larger you can check Fusion. This library ls really a group of smaller libraries each with it's own set of concepts, types and functions.

p5rn7vb

Comment on This Page

There are 0 comments