Supplemental Web Site: Use Brightspace for assignments, deadlines, other course information, and assignment submission

ECE 486 Code Commenting Requirements (ALL labs)

Overview

All C code submitted for ECE 486 should be commented to support the use of Doxygen to generate documentation directly from the source code. From the Doxygen www site: "Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, Tcl, and to some extent D."

Documentation Basics for ECE 486

Every file (.c or .h) should include a Doxygen header block (template below). Public functions should have Doxygen commenting in the .h (include) files of your code. Don't duplicate the function comments in the source (.c) files where these functions are defined. Private (static) functions in the .c file should include Doxygen comments (since they are not likely found in the .h file).
To indicate a Doxygen comment block, add an "!" or "*" character to the opening comment character sequence. You may use the C-style:
/*! ...comments... */
Or the C++ single-line comment style:
//! ...comments...
Do include normal (non-Doxygen) comments to describe algorithms, approaches, etc within your code. Use Doxygen primarily to clearly define the interface for others to use your code.
Doxygen generally assumes that that a comment block refers to the code immediately after the comment. (Don't leave a blank line between the comment block and the code.) You can tell Doxygen that the comment refers to the code before the comment block by including a "<" charater in the opening character sequence as in:
#define IN_BUF_SIZE 100 //!< Number of samples per input buffer
Generally, keep the comment with the actual definition/declaration, and Doxygen will figure out the actual thing you are documenting. You should avoid using \struct, \union, \enum, \fn, \var, \def, \typedef. (They are only needed if you are trying to put the documentation in one place, with the actual declaration/definition in another: Usually a bad idea.)
Using "groups" (@ingroup, @defgroup, @addtogroup) is encouraged, but not required. They can significantly improve the presentation of the end documentation. The same is true of "pages" (@mainpage, @page, @subpage). Read the Doxygen documentation if interested.

Comment Block Templates

File comment header: Use at the beginning of every file (source code or header file).
functions (Examples of function declarations)
#define (Examples of #define constructs)
enum and typdef enum (Examples of enum constructs)
struct and typdef struct (Examples of struct constructs)

Compiling the Documentation

You can use doxygen to generate a configuration file template using the "doxywizard" GUI, or (if you're old-school), run "doxygen -g" and then edit the generated "Doxyfile". Alternatively, you can download this Doxyfile which is close to what we'll use to browse your documentation and code. (This Doxyfile generates html documentation only.)
Put the Doxyfile in the same directory as the source (or in a parent directory), and run "doxygen". A "doc" subdirectory should be created containing the generated documentation. (To view html documentation, open "index.html" in the "doc/html/" subdirectory.

Example

As one example, you might check the documentation for the libece486 library that you are using for the STM32F4-Discovery labs. Viewing the source code for the various files in the library will show the doxygen comments used to generate the documentation. (Use the "Files" tab in the documentation to find the source listings).

ECE-486 Digital Signal Processing