User documentation of generic software components

The challenge is how to describe the abstract semantics in its full generality: just how widely is the component adaptable? This often requires creativity, and several tries--you might not realize how general the component is until you attempt to describe it carefully. Entirely new ways to use it may be suggested. Also you may have to define new concepts, by means of sets of requirements, in order to organize your descriptions coherently. The remaining discussion in this section will emphasize techniques for describing a component in its full generality and avoiding descriptions that would unnecessarily exclude certain uses. Once again, we look at examples of user-level generic component documentation from the SGI Web pages on STL. There are a few places where the SGI documentation does not describe components in their full generality, such as the merge function (see below). Specifying concepts The following definitions briefly summarize the terminology used in documenting generic software using concepts. Concept description: set of type requirements Concept: set of types that meet the described requirements Model of a concept: any type that satisfies the requirements Refinement of a concept: another concept with the same requirements plus additional ones (similar to class inheritance). If concept B is a refinement of concept A, then B has fewer models than A. Concept hierarchy (collection of concepts and their refinement relation) Specifying functions Consider the STL generic merge function. Do you see how it can it be used more generally than the SGI description implies? An effective way to describe the input-output relation computed by a function is in terms of preconditions, postconditions, and effects. precondition: a predicate that states what condition (relation of input variables) must be satisfied by any call of the function; sometimes called a requires clause. postcondition: a predicate that states what condition (relation of input and output variables) that is satisfied after the function call is completed, provided the precondition is satisfied; sometimes called an ensures clause. effects: a list of changes the function makes on variables other than those considered to be outputs of the function; sometimes called a side-effects or modifies clause. A function may throw an exception, in which it does not return in a normal manner and its input-output relation as described in the above terms does not apply. Any condition under which a function throws an exception is in general unrelated to the function's precondition: If the precondition is violated, an exception is not necessarily thrown. [Give an example.] Even if the precondition is satisfied, an exception may be thrown. [Give an example.] When it may be necessary to explain design decisions Sometimes, if some aspect of a component interface design is different from what is usually described in textbooks or seen in other libraries, it is helpful to the user to explain it. For example, the SGI documentation of the STL queue adaptor takes the trouble to explain why the pop member function has a void return type. Tips Finally, you can help the user by including tips for use of components. Tips go beyond how to use a component to describe how to use it well. Example: in the SGI description of the STL vector component, see the tips relating to storage management given in the notes at the end of the page.