Finally! A Doxygen filter for SystemVerilog available for free as GPL open source. (And I do mean finally!)
Are you still using MS Word to document your verification environment? Is your documentation out of date as soon as you send your final draft to the printer? Is your boss constantly hounding you about documenting your verification environment? Are you still trying to figure out how to leverage SciTE to generate pretty documentation? Are your coworkers struggling to extend your simple base class?
Well no more! Grab this filter along with my other doxygen tools, do a little light reading (and optionally a little more reading), edit a simple makefile and then – bam – peruse your code in doxygen documentation glory.
What does a SystemVerilog Doxygen filter do?
It converts SystemVerilog code into C++ like code that the doxygen source code documenting tool can then use to generate documentation.
Okay, but then what does Doxygen do?
Doxygen is a tool that automatically documents source code – especially Object Oriented source code – really well. It generates file documentation that includes everything in the file scope (typically classes and the occasional globally scoped macro, function, or variable) and a handy include diagram. It generates beautiful class documentation that lists member variables and methods. And, if you add doxygen styled comments then you can enhance the automatically generated documentation with things like complete descriptions of your members and methods along with examples of how to use your class. Understanding how to do this requires a little of that aforementioned light reading… but it’s pretty easy. For what its worth, I recommend using the “java_doc” style of comment.
Some things to keep in mind:
- It’s not filter based on a grammar; I developed this filter heuristically. This means that you will find bugs that will range from missing method documentation to totally funky class documentation. You will definitely see problems if you code in a manner that I would deem atypical.
- I’ve commented my strategy in the filter script pretty well – so you can change and edit as you see fit.
- Please file bugs! And include the failing code snippet in your bug.
File bugs at: http://bugs.intelligentdv.com to project “DoxygenFilterSV”
(There are a number of known issues, bugs, and feature requests filed against the doxyfiltersv project already – so you may want to check those out if you find anything).
- If you post your documented code on the internet (or even your intranet) I’d appreciate it if you kept my footer intact. Your users may appreciate being able to link to this site to learn more or even to file bugs against the filter. (You, of course, don’t have to include the footer, but it would be nice if you did!)
- Doxygen does not natively support SystemVerilog (Duh, that’s why you’re reading this); so this means that some stuff is documented with C++ syntax. Like what? Local variables are called “private,” pure virtual methods are documented as myfunction(…)=0; Mostly subtle differences like that. If you are familiar with C++ then you probably won’t even notice the difference.
But wait! There’s more!
I’ve also created a template doxygen configuration ‘doxyfile’ based on the default doxygen doxyfile that was generated by doxygen version 1.5.5. And from that I’ve created a delta file that has the settings that I’ve used to create the doxygen documentation that I’ve posted on this site. The template file includes the settings that you’ll need to integrate the filter into your own doxyfile.
AND – I’ve created a little script that converts an input doxygen template doxyfile and an input doxygen delta doxyfile into an output doxyfile. The script is also available here under GPL. It can be cascaded to generate a company standard doxyfile template (from a base template and base delta file) which can be used by individual projects with their own delta files. For example, to generate the posted VMM documentation I took my base doxyfile and base template to create my IDV doxyfile template. Then I rerun the script with that template and a VMM specific delta file to generate my VMM doxyfile. (It makes sense when you see the examples…) At this point you may be asking – what’s a doxyfile? And you may find the answer here.
How do I use the filter?
Doxygen has a built in hook for filters. Simply point that hook to the filter and you’re all set. If you don’t know how to do that then just read about the doxygen filter configuration straight from the source.
– OR –
just then take a look at the scripts that I’ve made to simplify this.
How do I get it?
- Best Way: with subversion – use svn to get the most recent version:
svn checkout http://svn.intelligentdv.com/Doxygen
(PC users take a look at the TortoiseSVN client – it makes synchronizing to an SVN repository from a PC easy.
- Other Way: The downloads page – just download the tarball of the latest released version. You’ll have to visit the site each time I release a new version to download it.
What’s in the Doxygen repository?
The repository has the following (SVN standard) directories:
- /trunk – the development branch (unstable!)
- /tags – numbered releases
- /branches – currently nothing
And in each revisioned release (or in the trunk) directory you’ll find:
- /doxyfile – template doxygen file and IDV delta file
- /filter – the doxygen filter perl script
- /html – the IDV footer
- /scripts – the script that converts input template and delta doxyfiles into an output doxyfile
I used a makefile to create my project specific doxyfile. I’ve got examples posted on the downloads page here:
- OVMdocs – makefile and template to generate OVM documentation
- VMMdocs – makefile and template to generate VMM documentation
- TealTrussDocs – makefile and template to generate Teal & Truss documentation
Note that each of these can also be checked out from SVN directly:
svn checkout http://svn.intelligentdv.com/OVMdocs
svn checkout http://svn.intelligentdv.com/VMMdocs
svn checkout http://svn.intelligentdv.com/TealTrussDocs
You can take a look at the resulting documentation here:
A couple of notes about my example scripts and the output:
- The fancy graphs require the use of dot which is part of the graphviz project. I leave installing this tool as an exercise for the reader… but it’s worth it! (Check out the docs that I’ve posted! Especially the inheritance diagram for ovm_object…)
- Those makefiles have pointers that assume that you’ve grabbed the doxygen scripts repository along with the source library repository. Since I haven’t made my svn repositories of any of the industry libraries available you will likely have to change the paths if you want to use those makefiles directly.
- To use the makefile just type: make clean && make docs
(Assuming, of course, that you both make and perl installed on your workstation.)
So next time your boss asks if you’ve documented your source you can say “YES!” with confidence.
Questions? Ask in the comments…
Bugs? File away!
PS – sorry this took so long to release. My ‘day job’ has been keeping me pretty darned busy lately.