Documentation

Doxygen in IDEs

CLion

• Doxygen Documentation in CLion

Visual Studio

• To switch to Doxygen, type “Doxygen” in the Ctrl+Q search box, or go to Tools > Options > Text Editor > C/C++ > > Code Style >> General, and choose your preferred documentation style

Type /** (and Enter in CLion) on the line above a header or prototype to get a documentation template.

Documentation Expectations

Using Doxygen: Quick Guide

From https://www.cs.cmu.edu/~410/doc/doxygen.html

There are two types of comments we want in your code. The first kind are comments at the beginning of each file which describes the file and lists things like author and known bugs. The second kind of comments are those that describe your functions and data structures. We want you to put comments on all your functions and data structures. You do not have to comment individual variable instances but are welcome to if you'd like.

Comments for Files

Each file needs to begin with the @file command stating the name of the file. This should be followed by a brief description of the file using the @brief command. If necessary, you can follow this with a more detailed description. Next you should put your name using the @author tag. This needs to be followed with a bugs section with a list of known bugs using the @bug command. If there are no known bugs, explicitly state that using the @bug command.

Template - put at very top

/** @file filename.cpp

* @brief Brief description of file.

*

* Longer description of file.

*

* @author Your Name

* @bug No known bugs.

*/

Comments for Functions and Data Structures

Before each function, data structure, and macro you should put a comment block giving at least a brief description using the @brief command. A brief description will suffice for your data structures but for you macros and functions you will need to use a few more commands. After your description, you should use the @param command to describe all of the parameters to your function. These descriptions should be followed by a description of the return value using the @return command. Note: When we say "each" function, that is not a strong statement. You can leave out simple helper functions, like a max() macro, so you don't waste time.

You can choose to comment your functions either in the header files where they are declared, in the source files where they are implemented or both. This is a matter of taste. If you put it in the header file, like in the example, then you should be sure to remember to update the comments with the latest details of the implementation. If you choose to put the comments in both places note that if there is a difference between the two sets of comments, the block at the declaration will superseded the one at the implementation. The long and short of this is that you should not put the comments in both. For assembly files, you can put the comments in the header file where they are declared.

Here is what we expect to see in the non-brief section of the function:

• Anything a user needs to know to decide whether this is the right function for them to use for a given job.

• Usage preconditions: must be called with interrupts disabled, etc.

• Any use of an unusual algorithm (in which case, cite it -- academic format or page title and URL)

• Why the code was written in a non-obvious structure.

• Warnings about how to extend the function without breaking it.

Not all of that will be needed for every function. Just make sure it is enough to make it clear what the function does and how it does it. Don't worry to much about this documentation stuff. If we feel that it is not up to what we want, we'll let you know with your grade report and probably won't take points off right now, but may in future projects. Make sure that the documentation is there and that it makes sense.

Template - put right above prototype

/** @brief Short description of function.

*

* Longer description of function.

*

* @param One for each parameter with the name and a description

* @return The word void or a description of what is returned

*/

Creating External Documentation

1. Download Doxygen

   1. Available for Linux, Mac OS, and Windows with or without admin rights

2. Install Doxygen

   1. All defaults are fine

3. Run Doxygen

   1. There are several options. The easiest for getting started is the Doxywizard, found in the Windows Start menu (if installed with admin rights).

      1. In Step 1 of the wizard, specify the working directory, likely C:\Program Files\doxygen

      2. In Step 2, in the Wizard tab, within the Project topic,

         1. provide at least the project name.

         2. set the source code directory to the folder that contains the cpp file(s).

         3. set the destination directory to the same folder as the source code but with docs at the end.

      3. In the Mode topic, you can choose Documented entities only, and optimize for C++ output.

      4. In the Output topic, choose HTML, with navigation panel, with search function.

      5. In the Diagrams topic, for a program with no classes you can choose No diagrams.

      6. In the Run tab, click Run doxygen.

   2. Another option to run doxygen is through the command prompt or Terminal in Windows, Visual Studio, or CLion. (necessary for non-admin installation)

      1. Change directory (cd) to the folder containing the doxygen.exe file

      2. Run doxygen -g (or .\doxygen -g) to create a new Doxyfile configuration file

      3. Edit the created Doxyfile in a text editing program like Notepad++.

         1. Customize PROJECT_NAME

         2. Set output directory to your solution folder with docs at the end similar to:

            1. OUTPUT_DIRECTORY = "C:\Users\username\OneDrive - Florida Gulf Coast University\Visual Studio Projects\SolutionName\docs"

      4. Move the Doxyfile to your project folder

      5. Run doxygen on the Doxyfile

         1. For example: C:\Users\sdvansel\OneDrive - Florida Gulf Coast University\Visual Studio Projects\SandboxW\SandboxW>"C:\Users\sdvansel\OneDrive - Florida Gulf Coast University\Visual Studio Projects\doxygen-1.9.2.windows.x64.bin\doxygen" Doxyfile

            1. Note, I had changed directory to the project folder within the solution folder containing the Doxyfile and then put the full path to doxygen.exe in double quotes since the path contained spaces.

            2. For complete doxygen documentation, you should have no warnings

4. Publish documentation

   2. 1. Commit and push the project, making sure to add the generated docs folder and contents (you may need to check the box in CLion).

      2. In the GitHub.com repository settings, in the Pages section, under Source, select the docs folder.

      3. Once the Pages settings page no longer says "currently being built", your documentation will be accessible through a browser at https://username.github.io/repositoryname/html/

         1. Note, for Doxygen, you need to add html to the end of what you see in GitHub Pages settings

         2. Put a link to this page in your README. How to create links in markdown