Order Documentation to Support Function Usage [DI14]
Tip DI14
When documenting a function, you have many choices on how to order different parts of the documentation. The primary goal of function documentation is to enable another programmer to successfully use a function, so you want to order documentation toward that goal.
The following is a recommended order for documentation:
Overview description: An overview provides the core description of what the function does. This is the most fundamental way to get a summary of what’s important to know about a function, so put it up front.
Parameters: Parameters are the fundamental data (typically inputs) required to call a function. Placing it before return documentation follows an intuitive input-output order for a sequence of operations.
Return value: Return values are the next most fundamental part of using a function as they provide the primary way to get output data from a function.
Exceptions: Exceptions are another way to communicate “output” from a function. However, they are typically used less commonly than return values, so exception documentation is typically best placed after return documentation. Understanding exceptions thrown by a method is still an important piece of knowing how to properly use a method, which is why exception documentation should come before remaining information.
Maintenance notes: Maintenance notes (which can often be documented with
<remarks>,\note, or@todotags) may often need to be documented for functions. However, since they aren’t critical for using a function, placing them after the core usage information allows them to be ignored by programmers who only need to use a function (not maintain/debug/modify it).
This order will keep the most important usage information (what will be most commonly used/referenced) first, with less-important or more maintenance-oriented documentation last. If you have other parts of documentation according to your standards, you can work them in as appropriate.
Using a documentation system with specific tags provides a more structured way to order many of these elements. Even if you’re not a documentation system with specific tags, you can still order documentation content as outlined above.