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

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

目次

はじめに

最近、設計書を書くときにいつも思うことがある。JavaやPythonなどのメジャーな言語は、javadocやSphinxのようにソースコードからドキュメントが生成できるから便利だなと。そして、なぜverilogはドキュメント生成ツールがないのだろうかと。


仕様変更や不具合修正があった場合、時間があるときはソースコードとドキュメントの両方を修正しようと思えるが、時間がないときはドキュメントは後で修正しておこう、となってしまう。そして、大体はドキュメントを修正しない。

ドキュメントとソースコードで一貫性をずっと保ち続けるのが非常に大変である。そもそも、ドキュメントを作成するのが面倒くさい。。。

verilogに対応したドキュメント生成ツールがないか色々と調べたが、どれもサポート対象外となっていた。verilogって結構とマイナー言語なんだなと感じた。

参考サイト:No.1のようにDoxygenにdoxverilogと呼ばれるパッチをあてる方法もあるようだが、4年も更新されていない。更新されていないと、不具合があった場合に修正してもらえないので、あんまり使いたくない。

さらに調べたところ、正式に対応はしていないが、使えそうなツールが2つあった。

Doxygenは、SystemVerilogがサポートされている。SystemVerilogもverilogもだいたい同じだし、使用できるだろうと思っている。参考サイト:No.2でも、ソースコードからドキュメントを生成している。

Natural Docsは、自分で定義した言語のドキュメントが生成できる。これなら、verilogからでもドキュメントが作れそう。ただ、Natural Docsは、日本語の参考サイトが非常に少ない。ざっと調べたところ、この参考サイト:No.3ぐらい。

何でも情報がのっているはずのqiitaでさえもNatural Docsに関する情報がなかった。なので、Natural Docsがどのようなものか使ってみることにした。

NDサポート言語

Natural Docs

Natural Docsは様々な言語で使用できるドキュメントツールで、javadocフォーマットにも対応している。Wiki参考サイト:No.4にも記載されているので、それなりの知名度はありそう。

Natural Docsは、1.5xと2.0xと2バージョンがある。1.5xはPerlを使ってドキュメントを生成するようだが、2.0xからは使わなくてもドキュメントが生成できるようになっている。その他にも2.0xは、ドキュメント生成時間が短くなったり、ドキュメント(HTML)のデザインや表示が変わったりと、大きな変化があるみたい。参考サイト:No.5

せっかくリニューアルされているので、今回はバージョン2.0xを使用する。

Natural Docsの環境構築

Natural Docsの設定をする。設定手順は、公式サイトに記載されているので、それにしたがって環境を構築する。


Natural Docsの入手

公式サイトに入り、「Download」ボタンをクリックする。

公式サイト2



次のページが表示される。Zip版とWindows版があるので、どちらかをクリックする。私はWindows版(上の方)を選択した。選択するとダウンロードが開始する。ちなみに、ダウンロードしたバージョンは、2.0.2であった。

公式3




Natural Docsのインストール

Natural Docsのインストールをする。ダウンロードしたNatural Docsを実行すると、次の画面が表示される。 「Next」を選択し、すべてデフォルト設定にしてインストールを進める。


インストール画面



インストールが完了すると、以下の場所にNatural Docsのフォルダが生成される。(※デフォルト設定の場合)

C:\Program Files (x86)\Natural Docs

Natural Docsの設定

ショートカットアイコンの作成と作業フォルダの指定

デスクトップ上で右クリックを選択し、ショートカットを作成する。

アイコン

リンク先は以下のように設定する。
D:\Work\NaturalDocs\NDConfig --pause-before-exitはNaturalDocsの設定ファイルを格納するディレクトリである。好きな位置でよい。

"C:\Program Files (x86)\Natural Docs\NaturalDocs.exe" D:\Work\NaturalDocs\NDConfig --pause-before-exit`

作成したショートカットをダブルクリックすると、次の画面が表示される。そして、指定したディレクトリに3つのファイルが生成される。これらの設定ファイルを修正し、環境を構築する。

  • Project.txt
    ・ドキュメントの生成場所やソースコードを読み込む場所、ドキュメント名を設定するためのファイル。
  • Languages.txt
    ・ドキュメント生成する言語を追加するために使用するファイル。
    ・ここで.vファイルを指定する。
  • Comments.txt
    ・ソースコード上のコメントを抽出するためのキーワードを定義するファイル。

DaturalDocs01

Project.txt

Project.txtは、ドキュメントの生成場所やソースコードを読み込む場所、ドキュメント名を設定するためのファイルである。このテキストファイルを修正する。


ドキュメント名前の設定

ドキュメントの名前を定義する。ドキュメントの名前は、Title:と記述することで定義できる。ここでは、次のように記載する。
Title: TestProject


ドキュメントの出力先を設定

ドキュメントの出力先を指定する。出力先は、HTML Output Folder:の後に記述する。ここでは、次のように記述する。
HTML Output Folder: ..\Doc


読み込むソースコードのフォルダを設定

ドキュメントを生成したいソースコードのフォルダを指定する。指定方法は、Source Folder:の後に記述すればよい。ここでは、次のように記述する。
Source Folder: ..\RTL


これで、ドキュメントの名前とソースコードの読み取り場所と、ドキュメントの出力先の設定が完了した設定を行う。

Languages.txt

Languages.txtは、ドキュメント生成する言語を追加するために使用するファイルである。ここの設定で、verilogファイルをソースコードとして認識させる。


verilogファイルを認識するための設定

Languages.txtを開き、次の記述を追加する。 


Language: Verilog

   Extensions: v vh

   Line Comment: //
   Block Comment: /* */
   Function Prototype Ender: ;
   Variable Prototype Ender: ;

各定義について説明する。

  • Language:
    ・言語の名前を定義する。TclやRubyのように、すでに定義されている言語の名前以外であれば、何でもよい。
  • Extensions:
    ・読み込むファイルの拡張子を定義する。ファイルが複数ある場合は、v vhのようにスペースを挿入すること。
  • Line Comment:
    ・単一コメントアウトの表記方法を定義する。
  • Block Comment:
    ・複数行コメントアウトの表記方法を定義する。
  • Function Prototype Ender:
    ・モジュール(関数)の記述が終わる位置を定義する。 ・Functionと定義してから、ここで定義した文字の範囲までドキュメントが表記してくれる。
  • Variable Prototype Ender:
    ・内部の信号名(変数)の記述が終わる位置を定義する。
    ・Variableと定義してから、ここで定義した文字の範囲までドキュメントが表記してくれる。

Comments.txt

Comments.txtは、ソースコード上のコメントを抽出するためのキーワードを定義するファイルである。デフォルトでかなりのキーワードが用意されている。

ただ、これらキーワードをverilogで使用するには、若干ニュアンスが異なる。

例えば、wireやassign、regなどの内部信号はVariableというキーワードを使うと思うのだが、これらは変数ではない。信号を意味するSignalやinternalSignal、Regiterあたりがしっくりくるが、そのようなキーワードはない。これらキーワードを追加してドキュメントを生成したい。そのようなときに、Comments.txtが役立つのである。

ただ、こだわりがなければ、特にこのままでもよい気がする。

今回は色々と試したいので、3つのキーワードを定義した。 

Comment Type: Module
Alter Comment Type: Function
   Plural Display Name: Module
   Keywords:
      Module, module

Comment Type: Parameter
Alter Comment Type: Constant
   Plural Display Name: Parameter
   Keywords:
      Parameter, parameter

Comment Type: InternalSignal
Alter Comment Type: Variable
   Plural Display Name: InternalSignal
   Keywords:
      InternalSignal, internalsignal

定義したキーワードについて説明する。

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


以上で、一通りの設定は完了した。次はいよいよソースコードにドキュメント用のコメント記述してゆくが、長くなったので次回のブログにする。

ちなみに、設定ファイルは以下の場所に保存している。

https://www.dropbox.com/sh/9vz87mp9skhzqnk/AABLqJhNMYsiqpbVYeB2GfV_a?dl=0

参考サイト

  1. doxverilogのインストール
    https://fpga.kice.tokyo/design/doxverilog
  2. SystemVerilog、VerilogをDoxygenでドキュメント化する
    http://marsee101.blog19.fc2.com/blog-entry-1454.html
  3. ASDocとNaturalDocs
    http://d.hatena.ne.jp/gravit/20100801/1280755128
  4. Wiki : Natural Docs
    https://en.wikipedia.org/wiki/Natural_Docs
  5. Wtaht's News in Natural Docs 2.0
    https://www.naturaldocs.org/whats_new_in_2.0/