The NaturalDocs comment style

NaturalDocs is the convention used by the UVM library. Set it as the default dialect with:

sv_doc_style = "naturaldocs"

Documentation blocks

A NaturalDocs block starts with a keyword header and is followed by prose:

// Function: get_name
//
// Returns the name of the object, as provided by the ~name~ argument in the
// <new> constructor or <set_name> method.

Recognized header keywords map to object kinds: Class, Function, Task, Variable (property), Group, Topic, Macro, Typedef, Module, Interface, Package, Port.

Header separators and banners

The separator may be a colon or a dash run, and headers are often wrapped in banner rules — all of these are recognized:

// CLASS: uvm_object
// Function -- get_name
//----------------------------------------
//
// CLASS -- NODOCS -- uvm_object
//
//----------------------------------------

The NODOCS marker

UVM tags blocks with -- NODOCS -- to keep them out of its IEEE extraction. The prose is still useful documentation, so by default it is kept (the marker is simply stripped). To omit those blocks instead:

# (model-level option; default is "include")
sv_naturaldocs_nodocs = "skip"

Inline markup

NaturalDocs	Rendered as
<symbol>	a cross-reference (:sv:obj:symbol``)
~code~	inline literal

Stray RST characters in prose are escaped automatically, so comments written for NaturalDocs render cleanly without RST surprises.

Detached blocks and groups

NaturalDocs blocks are frequently separated from the declaration they document (UVM puts extern prototypes and @uvm-ieee annotations in between). The extension scans every comment block and associates each with its symbol by name and source proximity, so detached blocks are found correctly.

Group: headers partition a class’s members into labeled sections, which render as subsection rubrics in the output.