Section 5.9 Documenting Functions
To preserve their value as abstractions, we should be able to use a function without understanding all of the code inside of it. The function prototype gives us some important information about how to use the function, but it doesn’t tell us everything. For example, can you tell how this function works?
double getMaxTemperature(int start, int range);
It clearly has something to do with the highest temperature. But what do
start and
range do? What kind of temperature is it returning? (Fahrenheit? Celsius?)
To use this function, we need to know more about it. Rather than requiring programmers to read (and understand) the code of the function to get that information, we can (and should) provide it as comments that go with the function. Here is an example of doing so:
/**
* @brief Finds the maximal temperature over a range of days
* @param start Day of the year representing the starting point
* of the range.
* Examples: Jan 1st = 0, Feb 1st = 31
* @param range How many days in addition to start day to search
* @return Max temp in degrees C
*/
double getMaxTemperature(int start, int range);
Lines 1-8 of the sample are all one big comment. This is a
block comment, which is a comment that can span multiple lines. Block comments start with
/* (like on line 1) and end with
*/ (like on line 8) Everything between those is a comment - the
* symbol on each line is not actually necessary, it just helps to clearly show what lines are part of the comment.
This particular comment starts with an extra * -
/**. That extra star doesn’t mean anything in the C++ language, but it is a convention used to indicate that this comment is a
Doxygen style comment. Doxygen comments use a structured syntax to provide documentation about functions and other parts of a program. Because the information is structured, it can be automatically extracted and used to generate documentation in a variety of formats. For example, the comment above could be used to generate a web page that describes the function
maxTemperature in detail or by a text editor to provide a popup with information about the function as you are writing code.
The rest of the comment communicates the information needed to correctly use the function:
- @brief
Provides a short description of the function. This should give a high-level overview of what the function does.
- @param
There should be one of these for each parameter of the function. First is the name of the parameter, then a description of what the parameter is for.
- @return
Describes what it is the function returns.
This is not an exhaustive list of the things that can be documented (there are things like
@author,
@bug @example, etc...). But these are the most critical items. When working on a programming team or in a class, there will likely be conventions for what items need to be included in your documentation.
In addition to documenting those aspects of the function, you can provide a longer description for the function after the @ items. This example does so to provide extra information about how the function does its job and what happens if it cannot:
/**
* @brief Get the average high temperature (in Fahrenheit) for
* the specified day of the year
* @param day Day of the year. Jan 1st = 1, Feb 1st = 32...
* @return degrees F
*
* This function will connect to weather.com to retrieve the
* average high temperature for the specified day. If a network
* error occurs, the function will return -1.
*/
double getAverageHighTemperature(int day);
You have attempted
of
activities on this page.
