まえがき
- Nimの標準ライブラリのドキュメント整備のissuesに参加したときに、Nimのドキュメントを書く方法についていろいろ知見を得ました
- NimでAPIドキュメント書いてドキュメント生成する方法について書きます。
APIドキュメントの書き方
Nimのドキュメンテーションコメント
Nimではコメントを書く時に#と書きますが、ドキュメンテーションコメントを書く時は##と書きます。
以下のように書きます。
## sample.nim はAPIドキュメントのサンプルです。
##
## これはトップレベルのドキュメンテーションコメント。
var v1* = 1
## v1 は1が入っています。
## 複数行のテキストも表現できます。
const
v2* = 2
## v2 は2です。
## こちらも複数行のテキストを表現できます。
v3 = 3
## v3 は非公開なのでドキュメントが生成されない。
type
SampleObject* = object
## SampleObject はサンプルオブジェクトです。
v: int
proc sampleProc*(n: int) =
## サンプルプロシージャです。
echo "Sample"
このコードからドキュメントを生成してみます。
以下のように実行します。実行するとsample.htmlが生成されます。
$ nim doc sample.nim
生成されたドキュメントは以下です。
ドキュメント記法(reStructuredText)について
Nimでのドキュメント記法はreStructuredTextです。
reStructuredTextの書き方については以下の記事がとても参考になります。
サンプルコードの書き方(runnableExamples)
サンプルコードの書き方ですが、runnableExamplesというNimの組み込みプロシージャを使います。
以下に使用例を示します。
## sample.nim はAPIドキュメントのサンプルです。
##
## これはトップレベルのドキュメンテーションコメント。
##
## 使用例
## ------
##
runnableExamples:
import sample
echo 1.add1()
## Output:
## 2
proc add1*(n: int): int =
## add1 は ``n`` に1加算する。
runnableExamples:
doAssert 1.add1() == 2
doAssert 10.add1() == 11
return n + 1
このコードから以下のAPIドキュメントが生成されます。
runnableExamplesのブロックのコードが、HTMLでコードブロックとして表現されています。
runnableExamplesでサンプルコードを実装すると以下のメリットを得られるので、積極的にこちらを使うべきです。
- エディタのオートコンプリートやシンタックスハイライトが効く
- コンパイルが通ることを検証できる
- サンプルコードが実際に動作することを検証できる
runnableExamplesのコードはデバッグビルドとリリースビルドからは無視されるので、実行時の無駄な負荷も発生しません。
reStructuredTextでもコードブロック記法があるので、以下のようにサンプルコードを書くこともできます。
## .. code-block:: Nim
## echo "Hello"
こちらはコンパイルが通ることの検証ができないのでrunnableExamplesが使えるときはそちらを使うと良いと思います。
runnableExamplesでは、実際にコンパイルしてバイナリを生成してサンプルコードを実行して正常終了することでサンプルコードを検証するような作りになっています。
サンプルコードのコンパイルが通らなかったり、サンプルコード内でエラーが発生したらドキュメントの生成はそこで停止します。
複数モジュールのドキュメント生成
以下のように、複数のモジュールをimportしているNimコードのドキュメントを生成したい場合があります。
src/
+- sample/
| +- module1.nim
| `- module2.nim
`- sample.nim
import sample/[module1, module2]
単純にnim docだけでドキュメントを生成すると、import先まではドキュメントを生成してくれません。
この場合は--projectと--index:onと--outオプションを使用します。
以下のように実行することでドキュメントを生成できます。
$ nimble doc --project --index:on -o:docs src/sample.nim
これでdocsディレクトリ配下にAPIドキュメントのhtmlが生成されます。
上記の例だと、sample.nimからimportしているサブモジュールのmodule1、module2のドキュメントも生成されます。
実際にやってみた
迷路を生成するコマンド兼ライブラリのハイブリッドなモジュールを作成しました。
こちらのモジュールでも前述と同様にnimble doc --project --index:on -o:docsでドキュメントを生成しています。
生成されたドキュメントはGitHub Pagesで公開しています。
以下がそのページです。
こちらはGitHub ActionsをCIに使用しています。
masterブランチが更新されると自動でGitHub Pagesに公開されるようにしています。
以前僕が書いたQiita - Nim用のGitHub Actionsを作ってみたで作成した自作のGitHub Actionも使用しています。
まとめ
以下の内容について書きました。
- APIドキュメントの書き方
- ドキュメント生成コマンド
- サンプルコードの書き方
- 実際にやってみた例の紹介
APIドキュメントの書き方としては公式のlib/pure配下のドキュメンテーションコメントが参考になります。
困った時は標準ライブラリのドキュメンテーションコメントを読むのもありですね。
以上です。