RDK-V Documenting your Code

Why to Document?

Writing documentation improves the design of your code. Talking through your API and design decisions on paper allows you to think about them in a more formalized way. A nice side effect is that it allows people to contribute code that follows your original intentions as well.

How to Document?

RDK component code is documented following the Doxygen standards and guidelines. Doxygen is a popular open source tool for generating documentation from annotated C/C++ sources. Also Doxygen support documenting code written in other programming languages such as Python, PHP, Java etc.

Tools Required for Doxygen Documentation

The following tools are required to be installed in Linux machine (through apt-get install) to generate documentation with respect to various data flow diagrams.

1. doxygen: It is a tool for a documentation system for various programming languages such as C++, C, Java, Objective-C
2. graphviz: Rich set of graph drawing tools. It required to fulfil the need of a centralized documentation presenting all available tools in the graphviz package.
3. dot: Filter for drawing directed graphs. A graph that can be drawn as hierarchy. It reads attributed graph files and writes drawings.  By default, the output format dot is the input file with layout coordinates appended
4. perl: It is a script file used by doxygen and it should be present in the system
5. mscgen: Message Sequence Chart Renderer. This will help to make sequence diagram for Doxygen documentation.

Steps to Generate Document using Doxygen

The following are the steps to generate documentation using Doxygen tool.

1. Create a new folder “example_name" – This is where the final report will reside.
2. Go to directory “example_name”
3. Reference doxygen configuration file
   
   1. doxygen.dox - used for customizing the index page

   2. doxygen.css - style sheet file used for formatting html output

   3. Doxyfile - Configuration file that is needed for generating doxygen output

   4. RDK-Logo.png - RDK Logo

4. Check out all the RDK component source code (Source code must be Doxygen complaint) for which document needs to be generated, for example :

   • $ git clone "https://code.rdkcentral.com/r/rdk/components/generic/wifi" wifi

5. Edit Doxyfile and set all configurations as required, given below are examples

   • PROJECT_NAME  /* Name of the project */

   • INPUT   /* Path of source code provided as input for document generation*/

   • OUTPUT_DIRECTORY /* output folder path */

6. Edit doxygen.dox, if the index page needs to be customized, add module names that will be shown in output index page

7. Edit doxygen.css, for output formats, fonts, etc

8. Use the following command at the command prompt, to generate html report

   • $ doxygen Doxyfile

9. Doxygen Output HTML report will be available at  '/example_name/OUTPUT_DIRECTORY/html' folder, open index.html file to see Doxygen report

Steps to add module level information to components

Refer to Doxygen Guideline for uniform style of adding Doxygen comments for the RDK system.