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:

  1. 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 (.)
  2. 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
  3. 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.

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. */

4 Responses to “Using Doxygen (Comments) to Document SystemVerilog Code”

  1. Xing Says:

    Hi,
    Thank you for the contribution! I tried your scripts and they work fine.
    But for OVM macros such as
    `ovm_component_utils_begin(my_env)
    `ovm_field_int(num_agents, OVM_ALL_ON)
    `ovm_component_utils_end

    the documentation looks wrong. It mixed up with the next method comment.
    How to comment/or don’t to comment OVM macro?

    Regards,

    Xing

  2. Lisa Barbay Says:

    Hi,
    I am currently working for Company X[ edited by commenter’s request] – who extended the VMM class to MVM (they are using 1.0.1). Because they use Modelsim (Questa) — there was a lot of work involved in using this.
    But I used you tool and in 1 hour had documentation for both VMM/MVM — just based on Keywords.

    In your delta file, you might want to add some aliases to deal with keywords that are not c++
    # This tag can be used to specify a number of aliases that acts
    # as commands in the documentation. An alias has the form “name=value”.
    # For example adding “sideeffect=\par Side Effects:\n” will allow you to
    # put the command \sideeffect (or @sideeffect) in the documentation, which
    # will result in a user-defined paragraph with heading “Side Effects:”.
    # You can put \n’s in the value part of an alias to insert newlines.

    ALIASES += task=”\par Task:\n”
    ALIASES += depart=”\par Department:\n”

    I haven’t tried it — but I think it would work

  3. Lisa Barbay Says:

    This will work.

    I did a separate project and made a few handy aliases for ‘C’ [ a very flat language for Doxygen — but useful for building a website.

    I Aliased certain things that I like and it worked well:

    @function
    for function names

    @smem
    for structure memembers.

    Also the imaging links are really nice and help to make very easy to use documentation. I doxygenated my entire project as I coded and debugged it. It only took about 2 hours to create the Doxyfile and add image diagrams [ I am the only ‘c’ code person on the project — as a consultant; so really this was for my benefit — they have no dedicated validation engineers.

  4. Lisa Barbay Says:

    Hi Sean,

    I’ve seen Xing’s comments above about macros. I previously was using VMM and they converted all the `macros to classes — so the resulting Documentation looked fine.

    Now that I develop and teach UVM classes for Cadence — I always tell my students about this website. I am wondering why you have not put up the UVM 1.0 and 1.1 classes?

    If there is a problem with the `macros (no way — I want to rewrite those into classes)– Do you have an idea what is causing it? I will look into the Perl script if you have an idea of what is wrong.

    Thanks,
    Lisa

Leave a Reply