RDK Resources
[*RDK Preferred*]
Code Management Facility
RDK Forums
[RDK Conferences]
RDK Support
Archives
Papers & Presentations Archive
The purpose of this page is to provide a uniform style of Doxygen commenting for the RDK system. It will serve as a reference for current and future developers, while documenting the RDK system as it evolves. Ultimately, this will establish a consistent manner of documentation to strengthen the simplicity, readability, scalability, writability, reliability, and maintainability of the system.
Doxygen documentation can be generated in many formats(HTML, LaTeX, RTF, PDF, DOC) . HTML generation has support for more plugins and is easier to refactor as the system changes. Doxygen style should follow a consistent format to aid development across different IDEs. Additionally, it reduces issues when generating documentation.
/** * @tagname */
This is an example of a Java doc style Doxygen tag, since it uses the “@” symbol. Tags using the “\tagname” style are considered Qt style Doxygen tags.
There should be a header file containing only Doxygen tags or a separate Doxygen file that acts as a guide for the components, classes, methods, and variables (e.g. DoxygenMainpage.h). This can be done using the @mainpage tag at the top of the file.
There should be a header file containing only Doxygen tags or a separate Doxygen file that acts as a guide for the components, classes, methods, and variables (e.g. DoxygenMainpage.h). This can be done using the @mainpage tag at the top of the file.
/** * @mainpage Title of Document * */
Example of HAL system Doxygen Guideline (Note: source code was also modified to support correct generation of documentation)
A file should contain the @file tag at the top of the file. This supports generation of a file list tab on the main page. It also helps when files contain multiple classes.
/** * @file FileName.h * * @brief Brief file description. * * Verbose file description. */
Classes can be tagged in a number of different ways, but in general they are tagged using the @brief and @class tags before the class declaration. Having the @author, @date, and @version supports tractability as the system is versioned throughout the software lifecycle. When updating classes, update comments like this:
#include <iostream> using namespace std; /** * @brief Brief class description * * Verbose description of class. * * @class Class Name */ class ClassName { public: ClassName(); ~ClassName(); int var1; /**< Comment about public member variable*/ /** *@brief Brief method description * * Verbose description of method * *@param Parameter in the method’s definition * *@return Return value of method */ int Function1(int x); protected: int var2; /**< Comment about protected member variable*/ /** *@brief Brief method description * * Verbose description of method * *@param Parameter in the method’s definition * *@return Return value of method */ int Function2(int x); private: int var3; /**< Comment about private member variable*/ /** *@brief Brief method description * * Verbose description of method * *@param Parameter in the method’s definition * *@return Return value of method */ int Function3(int x); };
A struct can be tagged in the same way a class, but it is best to use the @struct tag. When updating structs, update comments like this:
/** *@brief Brief struct description * *@struct Struct Name */
Methods can be tagged in a number of ways, but in general the @brief, @details, @param, and @return tags are used before a method’s declaration or implementation. When updating methods, update comments like this:
/** *@brief Brief method description * * Verbose description of method * *@param Parameter in the method’s definition * *@return Return value of method *@retval Verbose explanation of return values */ int addNumbers(int x) { int sum = 0; sum += x; return sum; }
When updating variables, update comments like this:
int number; /**< Comment about number*/
Enumerated types are tagged using the @enum. When updating enum types, update comments like this:
/** *@brief Brief enum description * *@enum enum Name */
There are many tags you can use with HTML markup to create unique Doxygen documentation for a given file, class, method, or variable. The following are common tags that should be used when appropriate.
/** *@note A brief remark about the implementation to help clarify. * *@attention An important remark that may cause code to break. * *@warning An import remark that may depend on random conditions etc. * *@see A reference to a class or a link to documentation (e.g. http://document.1a.com) */
/** *@bug A remark about a known bug in the code. * *@todo A remark of what needs to be done to fix issues or remaining work. * */
/** *@a Formats following word in special font (used for hyperlinks) * *@b Formats following word in bold * *@em Formats following word in italic * *@c Formats following word in monospaced typewriter font * */
/** * - bulleted list item1 * - sub bulleted item1 * * - bulleted list item2 * */
/** * -# numbered list item1 * -# numbered list item2 * */
/** *@code i++; *@endcode */
Before generating Doxygen documentation, make sure to have the following:
Doxygen: http://www.stack.nl/~dimitri/doxygen/download.html (Contains Doxywizard )
Graphviz: http://www.graphviz.org/ (Click the Download link on the left side of the page)