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
* use HTML tags
 * @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.
(more…)