Documentation

Doxygen Documentation

In order to facilitate newcomers to this open source project, we encourage documentation on any newly added or modified features, files, methods, and classes via doxygen. For more information, visit doxygen manual.

Install

To install doxygen on ubuntu: sudo apt install doxygen

Note: you may need to install graphviz if you do not have it already: sudo apt install graphviz

Both code that is new to the project and exisiting code that has been modified should be properly documented

Running

You can view the project documentation by running doxygen Doxyfile. This generates an html directory with index.html inside - open to view.

Example

For this project, documentation is most often located in *.h files. Our goal is to have documentation for all *.h files, as well as all the classes and methods within. Below is an example file showing how to indicate that doxygen conformant comments should be scraped from the file, as well as the format expected for classes and methods.

Code

/*
// Copyright (c) 2016 Intel Corporation
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
*/

/**
 * \file
 *
 * Optional description of file
 */
#ifndef SIMPLEMATH_H_
#define SIMPLEMATH_H_

/**
 * A set of APIs for calculating the result of simple mathematical operations using integers
 */
class SIMPLEMATH {
 public:
  ...

 /**
  * Add two integers and return the result.
  *
  * @param a the first integer to be added
  * @param b the seconded integer to be added
  * @return the result of the addition of a and b
  */
  int add(int a, int b) {
     int result;
     result = a + b;
     return result;
  }
 ...
}
#endif //SIMPLEMATH_H_

Output

The doxygen generated documentation for our above example looks like this:

File view:

Class view: