Natural Docsを使ってverilogファイルからドキュメントを生成する その2

Natural Docs verilog ドキュメント生成ツール

はじめに


前回はNaturalDocsの環境構築を行った。
今回はソースコードにコメントを書き、ドキュメントを作成する。

目次

コメントの記述

前回定義した次のキーワードを使用して、コメントを書いていく。

  • Module
    　・モジュール宣言する記述箇所で使用する。
  • Parameter
    　・Parameter文の記述箇所で使用する。
  • InternalSignal
    　・wireやassign、regなどの内部信号の記述箇所で使用する。

書き方はシンプルで、次のようにコメントを書く。 

// キーワード: コメント対象となるもの
// 説明文


段落や太字など、それなりに表記の設定ができる。詳細は、参考サイトNo.1に記載されている。記述例を含め、丁寧に解説されているので、使用する前には一読した方が良い。

記載例 その1

例その１として、作成したキーワード「InternalSignal」を用いて、ドキュメントを作成する。 ソースコード上に次のコメントを書く。 

// InternalSignal: cnt00_reg
// データ送受信用カウンタ
reg [7:0] cnt00_reg ;


生成したドキュメントでは、これが次のように表示される。

NaturalDocs、ドキュメント01



記載例 その2

次の例として、作成したキーワード「Module」の説明文に「Parameters」という見出しを付けて、モジュールの入出力信号について説明するドキュメントを作成する。

ソースコード上に次のコメントを書く。 

/* Module: Adc
   Parameters:
    clk                  - 入力クロック：100 (MHz)
    rst_n                - 負論理のリセット信号
    ch_slct_in           - CHセレクト信号：1'b0-> CH0、1'b1-> CH1
    enpls_in             - AD変換開始トリガ信号：クロックパルス入力
    s_data_in            - ADCからのシリアルデータ
    config_data_out      - ADCへの設定データ出力信号
    sclk_out             - ADCへのシリアルクロック：2.5 (MHz)
    cs_nout              - チップセレクト信号
    ad_ch0_data_out      - CH0：10 bit ADデータ
    ad_ch1_data_out      - CH1：10 bit ADデータ
*/

module Adc(
    input  wire        clk,
    input  wire        rst_n,
    input  wire        ch_slct_in,
    input  wire        enpls_in,
    input  wire        s_data_in,
    output reg         config_data_out,
    output reg         sclk_out,
    output reg         cs_nout,
    output reg [ 9:0]  ad_ch0_data_out,
    output reg [ 9:0]  ad_ch1_data_out
);


生成したドキュメントでは、これが次のように表示される。

NaturalDocs、コメント02



注意点

コメントを書く時の注意点がある。これらをまとめた。

キーワードと:の間には、スペースを挿入しないこと。

キーワードと:の間にスペースを挿入してしまうと、そのキーワードの部分のドキュメントが生成されない。

コメント対象となるものと:の間にはスペースを挿入すること。

コメント対象となるものと:の間にスペースを挿入してしまうと、そのキーワードの部分のドキュメントが生成されない。 書式は必ず守らなければならない。

'があるコードは、正しく表示されない。

'の文字が存在するソースコードでドキュメントを生成すると、ドキュメント上でソースコードが表示されない。 

// InternalSignal: cnt00_reg
// データ送受信用カウンタ
reg [7:0] cnt00_reg=8'b0;


NaturalDocs、ドキュメント02


色々と調べた結果、コメントの書き方ではなく、'があるコードが原因であることが分かった。

どうやら、'があると、下図のようにソースコードが表示されないようである。NaturalDocsのバグか設定の不備かわからないが、ドキュメントを作成するときには気を付けた方が良い。

ドキュメントの生成

コメントを記載した次のverilogファイルを用いて、ドキュメントを生成する。
ソース

前回作成した、アイコンをダブルクリックする。

アイコン


次の画面が表示される。

コマンドライン


Building documentation...
Done.


と表示されたら、ドキュメントが生成されている。 ※これ以外の表記が出たら、ドキュメントが生成されていないので、ディレクトリや設定を見直すこと。

指定したドキュメント出力先のディレクトリには、次のファイルが生成されている。 生成ファイル
ドキュメントであるindex.htmlを開く。 表紙には、Project.txtで設定したタイトルなどが表示される。

サンプルドキュメント


左側には、verilogファイルが表示されているので、それをクリックする。 ソースコードで記載したコメントが表示されている。

サンプルドキュメント2


使ってみた感想


簡単な設定とコメントでドキュメントができるので、便利であった。特に、自分でキーワードが定義できるので、verilogに適した表記のドキュメントが生成できるのが、魅力的だと感じた。
ただ、表や図を張り付けることができないので、そこが少し残念であった。
ドキュメントとは関係ないが、コメントのよい書き方についてもっと学ぼうと感じた。。

最後に今回作成したドキュメントは以下に保存しておく。
サンプルドキュメント

参考サイト

  1. NaturalDocs：Documenting Your Code
    https://www.naturaldocs.org/getting_started/documenting_your_code/