Your programs should have two kinds of documentation. Implementation comments help other programmers understand the workings of your code, and the algorithms that you used. These should be added to your implementation file. I usually use single-line comments for these.

User-facing documentation, that needed by the users of your function, is generated by a documentation tool named Doxygen. Doxygen is used to generate HTML, PDF, LaTex, and other kinds user-facing documentation. You can see an example of the generated documentation here at the SFML Docs Web site.

Each comment starts with a /** token, and ends with a */ token. The individual elements begin with keywords, called tags. Each header file should begin with a file comment that contains these common elements.

• @file – Name of the file. Required if you are going to document functions, global variables and constants. Always use this.
• @author – your name. or ID (e.g. sgilbert)
• @date – date it was created (can be general, like: CS 150 S'25, MWAM)
• @version – version information about the library (optional)

Function Comments

Each function should also be documented. Place your function comments before the header line of the function. Here are the tags to use.

• Start your comment block with a single line ending in a period. This is the brief description of the function.
• @param – the name and description of every parameter to your function.
• @return – if the function returns a value, you should add this tag.
• @code (optional) – a block of code that will be syntax highlighted in the generated documentation. This block must end with a @endcode tag.

Here's the header file you're working on with the first function documented.

#ifnfef DIGITS_H
#define DIGITS_H
/**
  * @file digits.h
  * @author sgilbert (Stephen Gilbert)
  * @date CS 150 Spring 2025 SAT AM
*/

/**
  * Find the first digit of any integer n.
  * @param n the integer to check. May be negative.
  * @return the first digit of the integer n.
  * @code
  * int a = firstDigit(215);  // set a to 2
  * int b = firstDigit(-79);  // set b to 7, not -7
  * @endcode
*/
int firstDigit(int n);
#endif

Now, go and document the remaining functions on your own.

The documentation in the header file is for the client-what us necessary to use the function. In the implementation file, add implementation comments, in the form of a function plan, to help you to write the function.

These comments are intended for programmers, not for the clients of the function. Don't use Doxygen, but describe the algorithms and important implementation details.

For instance, here is my plan for lastDigit(), placed inside the body of the function:

// result <- |n| % 10

Implementing lastDigit

You should write your comments first, and then implement the function. The most straightforward solution just an if statement to select one path path for positive numbers, and another for negative numbers.

if (n < 0) { result = -(n % 10); }
else { result = n % 10; }

You could write a shorter version using the conditional operator like this, instead of an if statement.

result = (n < 0 ? -n : n) % 10;

For another short, one-line solution, which almost exactly matches the function plan, you can use the abs() function like this:

result = abs(n % 10);

However, a new C++ programmer might not realize that there are separate versions of the function in <cmath> (for floating-point numbers), and in <cstdlib> for (integers), and end up with an answer that was wrong, or code that does not compile.

The other two functions in our library are more difficult. Both of them require you to learn about a new kind of loop bounds, called limit bounds. Loops that do some processing and then check the results against a boundary condition are limit loops.

To write a limit loop, use the while loop, which executes a statement repeatedly while its condition remains true. The general form of the while loop looks like this:

while (condition)
{
    statements;
}

A while loop first evaluates the condition. If false, the loop terminates and the program continues with the next statement after the loop body. If true, the actions in the body are run, after which control returns to the loop condition. One pass through the body constitutes a cycle or iteration of the loop.

1. The test is performed before every cycle of the loop, including the first. If the test is false initially, the body of the loop is not executed at all. That's why this is known as a guarded loop.
2. The test is performed only at the beginning of a loop cycle. If the condition becomes false at some point during the loop, the program won’t notice that fact until it completes the entire cycle. When the program evaluates the test condition again, if it is still false, only then does the loop terminate.

A limit loop first does a calculation, and then checks to see if the calculation has reached a limit. Limit loops are used extensively in scientific, financial and graphical computing. Kinds of limits include reduction to zero, bisection, non-convergence tests (as in Calculus) and successive approximations. You'll use several of those in Lecture.

Here is a limit loop whose limit is the reduction to zero. This computes the sum of the digits in an integer, n:

int temp = n;
while (temp > 0)
{
    sum += temp % 10;
    temp /= 10;
}
cout << "The sum of the digits in " << n << " is " << sum << endl;

• The expression temp % 10 always returns the last digit in the positive integer temp.
• The expression temp / 10 returns the number without its final digit.

In this case, the condition that is being tested is the value of temp, which is changed each time through the loop. Once n reach its limit (0), the loop terminates.

More Loop Plans

Here are the plans that I created for each of the remaining two functions. Using limit loops, you should be able to complete these on your own.

Here is firstDigit()

// result <- |n|
// while result greater or equal to 10
//      result <- result / 10
// return result;

And, here is numberOfDigits

// Assume that 0 is a digit
// result <- |n|
// counter <- 1
// while result is greater or equal to 10
//     result <- result / 10
//     counter <- counter + 1
// return counter

If you are using the Codespaces IDE, you can see if Doxygen is installed by using the command: doxygen. If you see this:

then Doxygen is not installed in your instance. Install it like this:

Type Y and press ENTER and it will be installed for your current session. Type doxygen again, and you'll see a list of the program's options. Here are the ones you want to use:

• Type doxygen -g to generate a configuration file named Doxyfile. You can change its name if you like.
• In the configuration file, you might want to change these items. Just open it with your text editor, make the changes and save it.
• Change the Project Name to something appropriate
• Set Brief Member Desc to NO
• Set Javadoc auto brief to YES
• Set Warn no param doc to YES
• Set Generate Latex to NO
• Set Have Dot to NO
• Browse through the rest of the configuration file, and the online configuration help, to further customize your configuration. Save the configuration file, so you don't need to reconfigure if you need to install Doxygen again.

After you've created your configuration file, put it in the folder with your documented library files. Type the command doxygen Doxyfile and Doxygen will process your files and produce a new folder inside your project folder, named html.

To view your files (inside the CodeSpaces IDE), just type http-server in the terminal window and Control-Click the link that it provides you. Navigate to the index.html file in the html folder and click it, and you'll see the documentation for your library. When you're done looking at it, stop the http-server by typing Control-C in the terminal window.