Documentation

Document of project can be generated by veryl doc command. All public modules, interfaces and packages will be listed in it. (See Visibility )

If you want to add a detailed description, you can add documentation comment. In the documentation comment, Markdown syntax can be used.

The following formats are supported too.

• Waveform description based on WaveDrom
• Diagram description based on Mermaid

Each syntax can be used in wavedrom and mermaid code block.

Please refer the following for the detailed syntax.

• Tutorials | Mermaid
• Hitchhiker’s Guide to the WaveDrom

/// The detailed description of ModuleA
///
/// * list item0
/// * list item1
///
/// ```wavedrom
/// {signal: [
///   {name: 'clk', wave: 'p.....|...'},
///   {name: 'dat', wave: 'x.345x|=.x', data: ['head', 'body', 'tail', 'data']},
///   {name: 'req', wave: '0.1..0|1.0'},
///   {},
///   {name: 'ack', wave: '1.....|01.'}
///
/// ]}
/// ```
pub module ModuleA #(
    /// Data width
    param ParamA: u32 = 1,
    const ParamB: u32 = 1,
) (
    i_clk : input  clock        , /// Clock
    i_rst : input  reset        , /// Reset
    i_data: input  logic<ParamA>, /// Data input
    o_data: output logic<ParamA>, /// Data output
) {
    assign o_data = 0;
}

The available configurations are below. These can be specified in [doc] section of Veryl.toml.

[doc]
path = "document"

Documentation test

WaveDrom blocks can also be used as documentation tests by using wavedrom,test code block instead of wavedrom. The waveform signals are matched to module ports by name (with i_/o_ prefix and _n suffix removed automatically). Clock and reset signals are recognized and handled appropriately.

Documentation tests are executed through veryl test command along with other integrated tests.

The available wave characters are:

• p, P, n, N — clock signals (positive/negative edge)
• 0, 1 — logic values
• x, z — unknown / high-impedance
• . — repeat previous value
• =, 2-9 — data values (with data array)

/// 1-cycle delay register.
///
/// ```wavedrom,test
/// {signal: [
///   {name: 'clk',   wave: 'p........'},
///   {name: 'rst_n', wave: '0.1......'},
///   {name: 'din',   wave: '0.01.0.1.'},
///   {name: 'dout',  wave: '0...1.0.1'}
/// ]}
/// ```
pub module ModuleB (
    i_clk  : input  'a clock,
    i_rst_n: input  'a reset,
    i_din  : input  'a logic,
    o_dout : output 'a logic,
) {
    var r_data: 'a logic;

    always_ff {
        if_reset {
            r_data = 0;
        } else {
            r_data = i_din;
        }
    }

    assign o_dout = r_data;
}