ドキュメンテーション

プロジェクトのドキュメントは veryl doc コマンドで生成することができます。全てのパブリックなモジュールとインターフェース、パッケージがリストアップされます。（参照 可視性）

詳細な説明を書きたい場合はドキュメンテーションコメントを追加することもできます。ドキュメンテーションコメントではマークダウン記法を使えます。

以下のフォーマットもサポートされています。

• WaveDromによる波形記述
• Mermaidによるダイアグラム記述

それぞれの構文は wavedrom と mermaid コードブロック内で使用できます。

詳細な構文は以下を参照してください。

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

/// ModuleAの詳細説明
///
/// * リスト要素0
/// * リスト要素1
///
/// ```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 #(
    /// データ幅
    param ParamA: u32 = 1,
    local ParamB: u32 = 1,
) (
    i_clk : input  clock        , /// クロック
    i_rst : input  reset        , /// リセット
    i_data: input  logic<ParamA>, /// データ入力
    o_data: output logic<ParamA>, /// データ出力
) {
    assign o_data = 0;
}

設定可能な項目は以下の通りです。これは Veryl.toml の [doc] セクションで指定できます。

[doc]
path = "document"

ドキュメンテーションテスト

WaveDromブロックは wavedrom の代わりに wavedrom,test コードブロックを使うことでドキュメンテーションテストとしても利用できます。波形の信号名はモジュールポートと名前で照合されます（i_/o_ プレフィックスと _n サフィックスは自動的に除去されます）。クロックとリセット信号は適切に認識・処理されます。

ドキュメンテーションテストは他の組み込みテストとともに veryl test コマンドで実行されます。

使用可能なwave文字は以下です。

• p, P, n, N — クロック信号（ポジティブ/ネガティブエッジ）
• 0, 1 — 論理値
• x, z — 不定 / ハイインピーダンス
• . — 前の値を繰り返し
• =, 2-9 — データ値（data 配列と併用）

/// 1サイクル遅延レジスタ
///
/// ```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;
}