A new release of the syntax files set is now available. All of the syntax files have been updated to reflect recent changes to the SystemVerilog IEEE 1800 standard (up to the draft 1800-2009 release).

This includes syntax files for:
– Kate (KDE Linux Editor)
– Crimson (Windows Editor)
– SciTE (Windows Editor – with syntax color RTF copy support)
and
– GeSHi (PHP based Syntax Highlighter)

So what’s GeSHi? Awesomeness!

GeSHi is how I have color coded SystemVerilog code posted on my blog (using WordPress with the WP-Syntax plugin) — like here in this blog post.

And GeSHi is how I have color coded code posted in my WebSVN repository – like here in the SVtimers repository.

Yeah – GeSHi is pretty cool.
I’ve sent my syntax file to the GeSHi team – hopefully they’ll accept it in their release.

You can download this release here:

http://intelligentdv.com/downloads/index.html#syntaxfiles

-Syntax-2009-d8

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.

(more…)