Using Doxygen (Comments) to Document SystemVerilog Code
The scripts provided here at intelligentDV will document your SystemVerilog testbench code automatically. But that documentation would be a lot more useful with the addition of doxygen styled comments. In this post I’ll show you what doxygen documents automatically and how to improve that documentation by adding comments with examples of both the input and output
Without any special comments doxygen will parse your code and generate documentation that will show you all of your:
- files
- classes
- programs
- interfaces
- modules
- macros (defines)
- functions
- tasks
- variables
Additionally – the tool will show you the class member variables, member functions, inheritance hierarchy and usage (collaboration).
Unfortunately the tool can’t document what each is. For example: doxygen can ’see’ that you’ve written a classA that extends classB — but it can’t tell you what the classA is for or how to use it. This is where the addition of doxygen comments come in. You can augment the automatic documentation with comments that disccuss the details of how to use a given class or method, the intent of a variable, etc.
Every doxygen comment is essentially broken into a three parts:
- the doxygen trigger comment – an augmented comment so that doxygen knows that it needs to parse the contents for markup (we use /** and ///< ); NOTE: the brief must be terminated with a period (.)
- the brief comment – the title for the comment; this one is used in lists — for example, the brief class comment appears in th elist of classes alongside the class name
- the full comment – this is where you put your full description and can include doxygen tags as well as any HTML tags
The typical doxygen comment – in JAVADOC style – looks like this:
/**
* Brief Comment with a period to terminate.
* Full comment:
* the full comment can continue on multiple lines
* <em>use HTML tags</em>
* @note And use doxygen tags
*
*/An important note worth reiterating – the brief comment can continue over multiple lines and must be terminated with the period ‘.’ or the brief comment won’t be so brief.
I recommend using the JAVADOC style of comment. In addition to doxygen a number of documentation tools also support this format. That, and it’s a good looking format for comments.
I recommend using HTML tags only when there isn’t a corresponding doxygen tag that accomplishes the same.
A starter guide from the doxygen folks is here:
http://www.doxygen.org/docblocks.html
And all of the available doxygen markup is found on the doyxgen site here:
http://www.doxygen.org/commands.html
But no need to look at that just yet – After the break I’ll give you some cut-n-paste code that should cover most of your needs for:
- file
- class
- function/task/module/interface/program/constraint/coveragegroup
- variable
- enum
I recommend to comment – at a minimum – all files, classes, public members of those classes (including variables, tasks, functions, constraints, and coveragegroups), and any frequently used define macros.
After the break I’ll provide examples.
The Examples
All of these examples are copied directly from the test.sv file that is used to test each release of the filter.
At the top of every file have a comment that looks like this:
/**
* Test - brief comment.
* This file is a test of the doxygen filter script.
* This contains a semi-complete set of the SystemVerilog constructs
* that the filter script can handle
*
*
* @par Download the most recent version here:
* http://intelligentdv.com/downloads/
*
* @par File Bugs Here:
* http://bugs.intelligentdv.com/
* Project: DoxygenFilter
*
* @file test.sv
* @author Author O'Author
* @par Contact:
* http://intelligentdv.com/contact/
* @par Company:
*
*
* @version
* $LastChangedRevision$
* @par Last Change Date:
* $LastChangedDate$
* @par Last Change By:
* $LastChangedBy$
*
*/Note that I leave the copyright header as a separate header in a non doxygen block comment. This keeps the documentation from getting clogged up with a redundant (and typically large) comment.
This generates documentation that looks like this:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/test_8sv.html#_details
And note that the file list has the brief comment that we used above:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/files.html
Above every class declaration have a comment that looks like this:
/** * Test Class - Basic. * Just a basic class declaration. * "String in Quotes in a comment" * * @class test_class_basic * */ class test_class_basic; ...
This generates documentation that looks like this:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/classtest__class__basic.html#_details
And note that the class list has the brief comment that we defined above:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/annotated.html
Above every task / function should have a comment that looks like this:
/** * Pure Virtual Function. * Test pure virtual specifier * * @param A int - description of parameter A * @param B int - description of parameter B * @return int * */ pure virtual function int mypurevirtualfunction(int A, int B);
Note the use of the @param tag for method parameters and @return for the method’s return value.
The function’s documentation looks like this:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/classtest__class__basic.html#e51c4c3ae2938b96369ca9658f423b19
Note that the brief description defined in the comment is used in the class’ list of member functions here:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/classtest__class__basic.html
(scroll down a bit…)
A typedef enum should be commented like this:
typedef enum {A, ///< A State B, ///< B State C, ///< C State D ///< D State } alpha_enum_t; ///< Alpha State Enum Type
Note the use of the ‘to the right’ pointer inline comment. We comment both the type name and the enumerations.
The enum documentation looks like this:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/classtest__class__basic.html#a78fb021ca5776b90837c0efd1e1fde0
Similar to enums, class member variables should be commented like this:
local rand int m_local_int; ///< Private Int
And their documentation looks like this:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/classtest__class__basic.html
(Scroll to the documented private member variables).
Both constraint and covergroup members should be commented like this:
/** * Word Align Constraint. * Constrain m_public_bitvector to word align * */ constraint word_align { ...
And the constraint’s documentation looks like this:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/classtest__class__basic.html#dfaa7175af783be066a8d308b3b23fd7
Programs, modules, and interfaces are commented just like functions and tasks.
/** * BusB interface Block. * An interface with two lines of I/O * * @param clk bit - description of parameter clk * @param foo logic - description of parameter foo * */ interface bus_B (input bit clk, output logic foo); logic [8:1] cmd; ...
And the interface documentation looks like this:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/group__SVinterface.html#g979a28dcc7a63b6015d4413c0c132c5e
And again, note how the brief tag is used in the list of interfaces:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/group__SVinterface.html
There’s a bit more that you can accomplish using doxygin, but this should be enough to get you started.
You can find more examples in the aforementioned test.sv file here – the same test.sv that’s included in the Doxygen tools distribution here:
http://intelligentdv.com/downloads/index.html#doxygentools
Questions? Ask in the comments.
Issues? File a bug!
-/** Start Documenting. */