Documenting Code

Table of Contents

• 1. Building documentation
  • 1.1. Initial setup
  • 1.2. Updating documentation
• 2. Doxygen input files
  • 2.1. Sources
  • 2.2. Auxillary files
  • 2.3. Summary table
• 3. Documentation Style and Practices
  • 3.1. Documenting Functions
  • 3.2. Doxygen Grouping (modules)

Note

This file: src/CommandLineInterface/doc/DocumentingCode.md

Key concepts :

• Compiling documentation pages
• Writing documentation
• Documentation style and conventions

---

1. Building documentation

Code documentation is built by doxygen from markdown files in the source code directories, as well as notes included in source code files.

1.1. Initial setup

Documentation is built by doxygen and written in the ./dochtml/html directory.

To set it up on you local repo, follow these steps AFTER having cloned the repo.

mkdir dochtml
mkdir dochtml/html
cd dochtml/html
git clone https://github.com/<reponame> .
git checkout gh-pages
# remove other branch(es)
git branch -d master
cd ../..

Where reponame is for example milk, cacao or coffee.

For initial setup (creating gh-pages branch for the first time)

mkdir dochtml
mkdir dochtml/html
# exclude dochtml from repo
echo "dochtml/" >> .gitignore
git commit -am "added dochtml to gitignore"
cd dochtml/html
git clone https://github.com/<reponame> .
git checkout -b gh-pages
# remove other branch(es)
git branch -d master
# remove files to start from clean state. Change file list as needed
git rm -r src doc config configure.ac LICENSE Makefile.am 
cd ../..

---

1.2. Updating documentation

To update documentation locally:

doxygen

To push the changes to the git webpage:

cd dochtml/html
git commit -am 'updated doc'
git push

---

2. Doxygen input files

2.1. Sources

Documentation is generated by doxygen from multiple sources:

• pages.dox: top-level menu, which is the main page for doxygen-generated documentation. Contains entries such as @subpage page_pagename or @ref page_pagename that point to corresponding {#page_pagename} tags in any of the doc/xxx.md files.
• markdown files (<filename>.md) in doc/ directories
• documentation contained in source code (.c and .h files)

2.2. Auxillary files

Additional documentation that is not meant to be processed by doxygen (but can be linked from it) should be placed in directories named docdir. This can consist of pdf files, markdown file, or any other format.

2.3. Summary table

File / Directory	Github	Doxygen	Content
README.md	X		top level overview (application specific)
index.md	X		Main help index
pages.dox		X	top doxygen menu (application specific)
./doc/*.md		X	Generic documentation files
./docapp/*.md		X	Application specific docs
./src/doc/*.md		X	Generic documentation files
./src/docdir/*.md			non-doxygen documentation
./src/<modulename>/doc/*.md		X	Module documentation files
./src/<modulename>/docdir/*.md			Extended application documentation

Additional details:

• README.md: file appears on github's front page, and contains an overview description of the software package.
• index.md: top menu for github documentation page. Contains links to help pages in other directories. Standard links include:
  • installation guide, usually in ./doc/ directory
  • user's guide, usually in ./src/<modulename>/doc and ./src/<modulename>/docdir directories
  • programmer's guide generated by doxygen: ./html/index.html

---

3. Documentation Style and Practices

3.1. Documenting Functions

Doygen comments are included in .c files (not in .h files).

/**
 * @ingroup uselessfunction
 * @{
 * @brief A brief description of the function
 *         What is it for, what does it do ?
 *
 * Detailed description \n
 * Computes the <b>sum</b> of @p a and @p b, writes it as a string @p output.
 *
 * ### Why this function
 * To provide a documentation example.\n
 * Refer to macros as #MACRONAME()
 *
 *
 * #### subsection1
 * - item1
 * - item2
 * - item3
 *
 * #### subsection2
 * Documentation can include graphs using dot format.\n
 * Must have graphviz installed.\n
 * @dot work flow
 * digraph G {
 * rankdir="LR";
 * main -> a;
 * main -> b;
 * a -> sum;
 * b -> sum;
 * sum -> c;
 * c -> outstr;
 * }
 * @enddot
 *
 * ### Computation algorithm
 * Sum computed, then convert to string
 *
 * Example usage:
 * @code
 * char outstr[100];
 * some_function(2, 5, outstr);
 * printf("sum = %s\n", outstr);
 * @endcode
 *
 * @param[in]  a first number
 * @param[in]  b second number to be added to first one
 * @param[out] string output
 *
 * @return error code, #RETURN_SUCCESS if OK
 *
 * @see this other function: moreuseful_function()
 * @see http://somewebsite/
 * @note This is only an example
 * @warning Warning: this function does nothing useful
 */

inline static errno_t modulenamelowercase_compute_sum(
    int a,
    int b,
    char *output
)
{
    int sum;

    // nothing too surprising here
    sum = a + b;

    sprintf(output, "%d", sum);

    return RETURN_SUCCESS;
} // end of group

3.2. Doxygen Grouping (modules)

Tags defgroup and ingroup are used to group functions in modules.

See for example, in function_parameters.c :

 * @defgroup FPSconf Configuration function for Function Parameter Structure (FPS) 
 * @defgroup FPSrun  Run function using Function Parameter Structure (FPS)