Documenter¶

Features¶

The supported elements of the languages are represented in the following table:

Element	Verilog/SV	VHDL
FSM	Yes	Yes
Diagram	Yes	Yes
Description	Yes	Yes
Ports	Yes	Yes
Parameters/Generics	Yes	Yes
Constants	Yes	Yes
Typedef/Type	Yes	Yes
Signals	Yes	Yes
Always/process	Yes	Yes
Instantiations	Yes	Yes

Some elements can be avoided in documentation, or documented only if a comment hs been added.

Special comment symbols¶

A special symbol can be configured to identify the coments to be extracted from the HDL file. The special symbol must follow the comment characters of the language that is being used. By default the special character is !

The comments support MarkDown so it can be used to add some style to the documentation (links, tables,etc).

Example:

--! This is a description
--! of the entity.
entity counter is
port (
    clk: in std_logic; --! Clock comment
    out_data: out std_logic --! Description **port comment**
);
end counter;

Go to the documenter configuration section for more information.

Documenting files¶

General rules:

The comments without the special character will not be part of the generated documentation.
The description text and Wavedrom & bitfield diagrams must be described before the module declaration.
Multiline comments are allowed in the lines above a declaration.
If there are multilines and inline comments. Inline comments have priority.
MarkDown are allowed inside the comments. MarkDown tables, links, label or html coded embedded in the comments will be processed by the documenter.

Wavedrom¶

TerosHDL supports WaveJSON format in the module description. The format describes digital timing diagrams. You can learn more about it in the wavedrom tutorial.

Bitfield¶

TerosHDL can also parse data descriptions in the same way that wavedrom. You can learn more about bitfield.

Usage instructions¶

Open a VHDL/Verilog file and click the documenter button.

TerosHDL will open a preview of the generated documentation.

Select what to show and the verbosity of the documentation. It is possible to document everything, just the elements that are being comented or nothing for each documentation section available.
Export the generated documentation to PDF, MarkDown, HTML or SVG diagrams.
Every time the file is edited and saved, the preview will update the documentation automatically.