|
|
Writing Documentation for BoostDocumentation Structure |
Boost itself does not require any specific documentation structure. The C++ Standard, however, has very explicit requirements for the description of library components (Section 17.3). So for Boost libraries likely to be proposed for inclusion in the standard, it is highly desirable to structure documentation in a way that meets the requirements of the the standard. Doing so eliminates the need to rewrite the documentation for standardization.
Library developers should remember that for a library to be accepted as part of the C++ Standard Library, the proposal must include full wording. The committee will not do that work for you.
Beyond that, the documentation structure required for the standard is an effective way to communicate the technical specifications for a library. Although terse, it is already familiar to many Boost users, and is far more precise than most ad hoc documentation structures.
The following description is for the structure of documentation required by the standard. Boost libraries should also provided additional documentation, such as introductory, tutorial, example, and rationale material.
Each document contains the following elements, as applicable(1):
The Summary provides a synopsis of the category, and introduces the first-level subclauses. Each subclause also provides a summary, listing the headers specified in the subclause and the library entities provided in each header.
Paragraphs labeled "Note(s):" or "Example(s):" are informative, other paragraphs are normative.
The summary and the detailed specifications are presented in the order:
The library can be extended by a C++ program. Each clause, as applicable, describes the requirements that such extensions must meet. Such extensions are generally one of the following:
Interface convention requirements are stated as generally as possible. Instead
of stating "class X has to define a member function operator++(),"
the interface requires "for any object x of class X,
++x is defined." That is, whether the operator is a member is unspecified.
Requirements are stated in terms of well-defined expressions, which define valid terms of the types that satisfy the requirements. For every set of requirements there is a table that specifies an initial set of the valid expressions and their semantics. Any generic algorithm that uses the requirements is described in terms of the valid expressions for its formal type parameters.
Template argument requirements are sometimes referenced by name.
In some cases the semantic requirements are presented as C++ code. Such code is intended as a specification of equivalance of a construct to another construct, not necessarily as the way the construct must be implemented.(2)
The detailed specifications each contain the following elements:
Descriptions of class member functions follow the order (as appropriate)(3):
Descriptions of function semantics contain the following elements (as appropriate)(4):
Complexity requirements specified in the library clauses are upper bounds, and implementations that provide better complexity guarantees satisfy the requirements.
These conventions are for describing implementation-defined types, and member functions.
The Requirements subclauses may describe names that are used to specify constraints on template arguments.
The function semantic element description above is taken directly from the C++ standard, and is quite terse. Here is a more detailed explanation of each of the elements.
Note the use of the <code> ... </code> font tag to
distinguish actual C++ usage from English prose.
Preconditions for calling the function, typically expressed as predicates. The most common preconditions are requirements on the value of arguments, often in the form of C++ expressions. For example,
void limit( int * p, int min, int max );
p != 0 && min <= maxRequirements already enforced by the C++ language rules (such as the type of arguments) are not repeated in Requires paragraphs.
The actions performed by the function, described either in prose or in C++. A description in prose is often less limiting on implementors, but is often less precise than C++ code.
If an effect is specified in one of the other elements, particularly postconditions, returns, or throws, it is not also described in the effects paragraph. Having only a single description ensures that there is one and only one specification, and thus eliminates the risk of divergence.
The observable results of the function, such as the value of variables. Postconditions are often expressed as predicates that are true after the function completes, in the form of C++ expressions. For example:
void make_zero_if_negative( int & x );
x >= 0The value returned by the function, usually in the form of a C++ expression. For example:
int sum( int x, int y );
x + yOnly specify the return value; the type is already dictated by C++ language rules.
Specify both the type of exception thrown, and the condition that causes the
exception to be thrown. For example, the std::basic_string class
specifies:
void resize(size_type n, charT c);
length_error if n > max_size().Specifying the time and/or space complexity of a function is often not desirable because it over-constrains implementors and is hard to specify correctly. Complexity is thus often best left as a quality of implementation issue.
A library component, however, can become effectively non-portable if there is wide variation in performance between conforming implementations. Containers are a prime example. In these cases it becomes worthwhile to specify complexity.
Complexity is often specified in generalized "Big-O" notation.
Specifying the rationale for a function's design or existence can often give users a lot of insight into why a library is designed the way it is. More importantly, it can help prevent "fixing" something that wasn't really broken as the library matures.
Revised 29 November, 2003
© Copyright William E. Kempf 2001. All Rights Reserved.