4.3. Describing types

To document a type, describe what an object of that type represents. For example, if an object of type Cell is a cell in a linked list, say so. If an object of type Vertex represents information about a vertex in a graph, say that. Don't assume that the reader already knows.

Documenting structure types

---

A structure type has components that describe features or characteristics of an object. Document not only what an object of the structure type represents, but also what each component represents. You can use margin comments to document the components if you like. Alternatively, document each component in the comment just before the type. For example, here is documentation for a type, Cell, that is a cell in a linked list of strings.

  // An object of type Cell is a cell in a linked list of strings.

  struct Cell
  {
     char* str;     // The string in this cell.

     Cell* next;    // A pointer to the next cell, or
                    // NULL if there is no next cell.
  };

Here is an example of a type that represents an edge in an undirected weighted graph.

  // An object of type Edge represents an edge in an
  // undirected weighted graph.

  struct Edge
  {
    int    vertex1;   // This edge connects vertex1 and vertex2.
    int    vertex2;   
    double weight;    // The weight of this edge.
  }