Documenting OVM based verification code: Natural Docs help needed

OVM
1

Hi All,
I see that OVM-2.0.2 release comes with a nice Natural Docs generated html document. I wish to document my OVM-2.0.2 based environment similarly and want to know about the relevant filters etc. used with Natural Docs for System Verilog code documentation.

Presently I use doxygen with the System Verilog filter but I suppose that still has minor issues with it.

2

This question is more for the OVM Technologists on this forum. Hoping for a quick revert.

3

Natural Docs doesn’t do the thorough parsing that doxygen does, so adding SystemVerilog support is straightfoward.

Here’s the additional information in the Languages.txt file for SytemVerilog

Language: SystemVerilog
Extensions: sv svh
Line Comment: //
Block Comment: /* */
Package Separator: ::
Enum Values: Global
Class Prototype Ender: ;
Function Prototype Ender: ;
Variable Prototype Ender: ;
Method Prototype Ender: ;
Line Extender: \

4

Presently I use doxygen with the System Verilog filter but I suppose that still has minor issues with it.

I actually prefer to use Doxygen with the SystemVerilog filter provided by intelligentDV. Natural Docs is more pleasing visually, but I like the way Doxygen provides direct links to the line in the source code where an item is defined and hyperlinks references in the source code.

Both tools are good and it just comes down to your personal preference. More important than the choice of tool is the presence of comments!

5

Thanks Mark Glasser and Scott Roland, appreciate it.

This information is useful to a lot of us wanting to document our OVM based code.

Another related question: The search function in doxygen does not work unless the html files are hosted on a webserver. Is this true of Natural Docs as well?

6

I really liked the relation from document to directly linking actual code on click as it is available on ovm2.0.2.

I tried with the setting given by Mark. Documents are generated but I am not able to get link on function/variable/class to actual code from HTML.

Do I miss something ?

I am using “perl NaturalDocs -i ~/ovm-2.0.2/src -o HTML try_docs -p ~/NaturalDocs”

Regards,
Kinjal

7

Another related question: The search function in doxygen does not work unless the html files are hosted on a webserver. Is this true of Natural Docs as well?

Good point.

Doxygen requires a web server, since the search is implemented in PHP (which is processed on the server).

Natural Docs does notrequire a web server, because search is implemented in javascript (which is processed in the browser).

8

First thank you for your code snip, however, like the other post, I found it incomplete. NaturalDoc’s flags a problem:
“Method Prototype” line since it does not exist in Topics. Do you have the snip from topics as well?

…kyle

9

Thanks for the information in this thread. It made my NaturalDocs run with SystemVerilog code.

Just a slight problem though - there is only one class popping up in the documentation!

And after some grep I can see at least 18 classes in this small verification code. NaturalDocs tells me it parses 25 files (all .sv and .svh files).

Am I missing some small information? Something that might hide classes?

I’ve tried both the NaturalDocs OVM release (based on 1.35) and 1.4 with SystemVerilog added.

Any Ideas?

Best regards!