Information for developers

Table of Contents

• Running Unit Tests
• Library document generation
  • General Content inside the Documentation
  • Documenting the Code
  • File Structure of the Documentation
  • Generating a new Local Documentation
  • Copying the online Documentation to local PC
  • Automatic Documentation Deployment with github ACTION

This chapter gives some basic information aimed primarily at developers of the library.

Running Unit Tests

TODO: There's probably a nice way to run the unit tests from Arduino IDE or PlatformIO. Please document that here.

Here's how to run the unit tests from the command line:

#cd to this repository root 
cmake .
make
ctest -V

Library document generation

The library documentation is automatically generated by Doxygen which combines all information from the source code with the markdown files from the ./Documents/src folder. The full documentation is listed on github pages.

See also:

• Doxygen Manual
• Doxygen Awesome Style

General Content inside the Documentation

The general content is written in markdown files. Each file greats one page on the toplevel of the navigation tree. Inside the file structure can be generated by headers and all doxygen commands can be used as well. The pages are listed in alphabetical order of the filenames in the navtree, thats why the filenames are starting with numbers.

Documenting the Code

Doxygen is very powerful in generating documentation from annotated C++ sources. Therefor it is most importend that all the source code files are proper documented.

The documentation for all variables, functions, classes, defines and so on is placed directly inside the header files.

Each Header file should start like this: see N2kTypes.h

/*************************************************************************//**
 * \file  filename.h
 * \brief A brief description of the File
 * 
 * Add more detailed explanation of the content, purpose, background 
 * information. A bit more ist better ;)
 */

Documenting an enum: see tN2kChargeState

/*************************************************************************//**
 * \enum tNewEnum
 * \brief A brief description of the enum
 * 
 * A more detailed Description helping the user to understand the meaning 
 * and the usage.
 * 
 */
enum tNewEnum  {
                            /** Description of State 1 */
                            State1=0,         
                            /** Description of State 2 */
                            State2=1,         
                            /** Description of State 3 */
                            State3=2,       
                            /** Description of State 4 */
                            State4=3 
                          };

Documenting a class is similar to the enum, just replace \enum with \class.

Documenting a function: see SetN2kPGN129802

/************************************************************************//**
 * \brief A brief description of the function
 * 
 * A more detailed Description helping the user to understand the meaning 
 * and the usage.
 * 
 * \param var1      Description for parameter 1
 * \param var2      Description for parameter 2
 * \return true     Description for successful
 * \return false    Description for aborted
 */
bool function(int var1, unsigned char var2);

Other useful doxygen commands for linking things together

\ref    Reference to on object of the documentation 
 
\sa     See Also Paragraph inside the documentation

File Structure of the Documentation

All Files for the documentation are placed in a specific folder structure. This is important, because this structure is part of the configuration file **(./Documents/src/DoxyConf)**.

...
./Documents                 --> Main folder for Documentation 
./Documents/Images          --> General Images that speak for itself 
./Documents/Schematics      --> Schematics for Hardware
./Documents/src             --> Documentation Source for doxygen, all 
                                markdown files and the doxygen config file
./Documents/src/doxyStyle   --> All additional html styles
./Documents/src/images      --> all small images and pictograms just used 
                                for documentation
...
./src                       --> source code of the library

Generating a new Local Documentation

Before committing new content to github it is mandatory to test all changes locally. Therefor you can generate the doxygen html docu. Download doxygen to your PC from download

Step by Step

1. fork the library to your github account
2. clone this fork locally to your PC
3. make a directory "./build/docs" (here the doxygen output will be placed)
4. make your changes
5. move into the folder "./Documents/src"
6. run doxygen

   doxygen -g DoxyConf

7. see the results under "./build/docs/html/index.html"
8. see warnings under "./build/docs/doxygen_warnings.log"

Warning

Do never push the generated documentation back to the github repository. Therefore it is useful to add "./build/*" to your local gitignore file!

Copying the online Documentation to local PC

There is a way to download the full documentation to your local PC. Go to githup Docu and clone all the files.

Automatic Documentation Deployment with github ACTION

In order to keep the documentation always up to date there is a github workflow in place which always get triggered when new changes were pushed to the master branch. The workflow is written in the file "./github/workflows/doxygen-gh-pages.yml" It generates the html documentation and push it to the branch "gh-pages". The "gh-pages" branch is the published under https://ttlappalainen.github.io/NMEA2000/