Documentation

It's important to keep software projects well-documented so that newcomers can quickly get up-to-speed and have a reference when questions arise. One common problem with software documentation is that it is easy for the documentation to get out-of-sync with the code, since the code is constantly updated and documenting it is often an afterthought.

One way to help with this is to put the documentation inline with the code, which is what we do for this project. We use a program called Doxygen that parses specially-formatted comments in our code and turns them into a searchable website that can be easily viewed. Note that this is very similar to a program called javadoc that many GT students are probably familiar with using in class.

Another way to improve documentation practices is by requiring code to be well-documented before merging GitHub pull-requests, which is something we're getting better at doing.

Doxygen Comment Formats

Doxygen has support for many different languages, but the comment syntax differs a bit. Below are a couple examples, but you should check out the official Doxygen docs for more info.

C++

/**
 * a normal member taking two arguments and returning an integer value.
 * @param a an integer argument.
 * @param s a constant character pointer.
 * @see Test()
 * @see ~Test()
 * @see testMeToo()
 * @see publicVar()
 * @return The test results
 */
 int testMe(int a,const char *s);

Python

class PyClass:

    
    def __init__(self):
        self._memVar = 0;

    
    def PyMethod(self):
        pass

    
    classVar = 0;

    

Additional Documentation

In addition to turning inline code comments into documentation, Doxygen can also include docs in other formats. This page that you are viewing right now and several others are written in Markdown. See the files in doc for examples.

Compiling the documentation

To build the documentation website, run doxygen from the root of the robocup-software project. This will place a bunch of files in api_docs/html. Open the index.html file in a browser to view the site.

Our documentation website automagically updates everytime someone pushes the master branch of the repository. This is setup through circle-ci - see the autoupdate-docs.sh script to see how this is done.

Further configuration

Doxgen looks at the Doxyfile in the root of our project to configure things such as which files to include and how to display the output.