22
8

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 5 years have passed since last update.

NimAdvent Calendar 2019

Day 4

NimでAPIドキュメントを書く

Last updated at Posted at 2019-12-03

まえがき

APIドキュメントの書き方

Nimのドキュメンテーションコメント

Nimではコメントを書く時に#と書きますが、ドキュメンテーションコメントを書く時は##と書きます。

以下のように書きます。

sample.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

生成されたドキュメントは以下です。

sample.png

ドキュメント記法(reStructuredText)について

Nimでのドキュメント記法はreStructuredTextです。
reStructuredTextの書き方については以下の記事がとても参考になります。

サンプルコードの書き方(runnableExamples)

サンプルコードの書き方ですが、runnableExamplesというNimの組み込みプロシージャを使います。
以下に使用例を示します。

sample.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ドキュメントが生成されます。

sample2.png

runnableExamplesのブロックのコードが、HTMLでコードブロックとして表現されています。

runnableExamplesでサンプルコードを実装すると以下のメリットを得られるので、積極的にこちらを使うべきです。

  • エディタのオートコンプリートやシンタックスハイライトが効く
  • コンパイルが通ることを検証できる
  • サンプルコードが実際に動作することを検証できる

runnableExamplesのコードはデバッグビルドとリリースビルドからは無視されるので、実行時の無駄な負荷も発生しません。

reStructuredTextでもコードブロック記法があるので、以下のようにサンプルコードを書くこともできます。

## .. code-block:: Nim
##    echo "Hello"

こちらはコンパイルが通ることの検証ができないのでrunnableExamplesが使えるときはそちらを使うと良いと思います。

runnableExamplesでは、実際にコンパイルしてバイナリを生成してサンプルコードを実行して正常終了することでサンプルコードを検証するような作りになっています。

サンプルコードのコンパイルが通らなかったり、サンプルコード内でエラーが発生したらドキュメントの生成はそこで停止します。

複数モジュールのドキュメント生成

以下のように、複数のモジュールをimportしているNimコードのドキュメントを生成したい場合があります。

src/
  +- sample/
  |   +- module1.nim
  |   `- module2.nim
  `- sample.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しているサブモジュールのmodule1module2のドキュメントも生成されます。

実際にやってみた

迷路を生成するコマンド兼ライブラリのハイブリッドなモジュールを作成しました。

こちらのモジュールでも前述と同様に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配下のドキュメンテーションコメントが参考になります。
困った時は標準ライブラリのドキュメンテーションコメントを読むのもありですね。

以上です。

22
8
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
22
8

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?