DenoモジュールにJSDocを書くとdoc.deno.landでドキュメントを見られて超便利だぞ
みなさま、Denoモジュールの開発はしているでしょうか。その際に説明は書いているでしょうか。
今回は、Denoのドキュメントジェネレーターサイトのdoc.deno.landの紹介です。
doc.deno.landはドキュメントサイト…ではない？
doc.deno.landは、その名の通り、Denoのモジュールのドキュメントをまとめたサイトです。
…と思っていましたが、その実態は、deno docコマンドの結果を整形して表示するWebアプリと言ったほうが良いかもしれません。
doc_websiteリポジトリのソースを見ると、内部でdeno doc [sourcefile] --json --reloadを実行し、その結果を処理していることが見て取れます。
deno docコマンドは、引数として渡されたファイル内でexportされているメンバー（関数、クラス、定数など）のJSDocを表示するコマンドです。
exportされていないものやprivateに指定されているものは表示されません。
で、doc.deno.landのページのパスは、以下のようにhttps://doc.deno.land/[URL]という形式になっています。
- https://doc.deno.land/https/deno.land/std/fs/mod.ts
- https://doc.deno.land/https/deno.land/x/oak/mod.ts
つまり、doc.deno.landは渡されたパス（上記のhttps/deno.land/std/fs/mod.tsやhttps/deno.land/x/oak/mod.ts）に応じてドキュメントを動的に生成しているのですね。
表示例
以下に、自作モジュールを用いて、doc.deno.landの表示例を示します。
ClassとInterfaceを含む例
先日の記事で、textdbというモジュールを紹介しました。
モジュールのページはこちらです。
そしてそのドキュメントがこちらです。
クラスの場合、コンストラクタやメソッドなど、良い感じに分割されて表示されます。
また、JSDocで@paramのように記載したところは強調されて表示されるのでわかりやすいです。
コードブロックと定数を含む例
以下の記事ではmarkup_tagというモジュールを紹介しました。
モジュールのページはこちらです。 ドキュメントはこちらです。
JSDoc内部にコードブロックを配置すると、doc.deno.landのほうでも良い感じにハイライトしてくれます。
また、定数にもコメントを書いておくと、表示に反映してくれます。
deno.land/x以外のファイルを対象にする例
deno runやdeno installに引数として渡すファイルは、実行環境からアクセスできればよく、ローカルのファイルでも、Web上に公開されているファイルでもよいのでした。
deno docも同様ですし、それを使っているdoc.deno.landも同様です。
つまり公式のdeno.land/xではなく、 x.nest.landに公開したモジュールの説明も、さらにGitHubやGistに置いているモジュールの説明も表示できてしまう のです[1]。面白いですね！
nest.landの例
例えば、上記のmarkup_tagはnest.landにも公開しています。
nest.landはdeno.land/xと違い、モジュール名に-を使えるので、markup-tagという名前になっています。
ドキュメントはこちらです。
nest.landの仕様上、バージョンナンバーが必須とはなりますが、deno.land/xに公開したものと同様にドキュメントが表示されています。
Gistの例
以下の記事で紹介したdenotreeも見てみましょう。このファイルはGistに公開しています。
ドキュメントはこちらです。
まあこれはCLIの練習として作ったものなので、JSDocどころかexportもしっかり行っていないため、説明としてはかなり不足しています。
しかし、doc.deno.landで表示できるということはわかると思います。
難点があるとすれば、GistだとファイルURLがhashなので、必然的にドキュメントのURLも非常に長いものになってしまうということでしょうか。
おまけ：JSDocはLSPでも表示される
JSDocで説明を書いておくことで、LSPで説明を表示することができます。
coc.nvimでのhoverの例
エディタから離れずに参照できるので、READMEに詳細な説明があるよりも、こちらに簡単な例がある方がありがたいこともあります。
おわりに
Denoのドキュメントジェネレーターが便利だという紹介でした。
JSDocをちゃんと書く必要はありますが、モジュールとして公開する場合は、それなりに説明を書く必要があるのは変わりません。
その場合、「実装はプログラムファイル」「説明はREADME（あるいは専用ページ）」と分かれるよりは、両方をプログラムのファイルの方にまとめてしまったほうが管理が楽かな、と思いました。
コードを編集した際にそれをドキュメントへ反映するのも忘れづらいですし。
ドキュメントの書き方・まとめ方に悩んでいる方は、今回の方法も試してみてはいかがでしょうか。
-
denoコマンドにしてみれば、読む先がdeno.landだろうがgithubusercontent.comだろうが気にしていないでしょう ↩︎
Discussion