新春特別企画

ドキュメントの構造化による,良いドキュメントの作成方法

この記事を読むのに必要な時間:およそ 3 分

ESDoc

ESDocは,JavadocやJSDocなどと同じようにソースコード中の/** @foo bar */というコメントをもとにドキュメント(HTML)を生成するツールです。筆者が2015年4月から開発を行っています。

最近ではReactiveX/RxJSLinkedIn/hopscotchLonlyplanet/rizzo-nextなどのプロダクトに採用され始めています。もちろんESDoc自身のドキュメントもESDocで作られています。

このESDocは前述したドキュメントの要素と性質にアプローチするための様々な機能を提供しています。それらの機能について簡単に紹介します。

ドキュメントコメント

5つの要素のうち「参照」⁠つまりAPIリファレンスに対応するための機能がドキュメントコメントです。JavadocやJSDocと同じようにソースコード中に特定の書式でコメントを書くことで,そのコメントをもとにドキュメントを生成する機能です。

/**
 * sums two values.
 * @param {number} a - a first value.
 * @param {number} b - a second value.
 * @return {number} result value.
 */
function sum(a, b) {
  return a + b;
}

マニュアルの統合

5つの要素のうち「導入」⁠操作」⁠事例」⁠履歴」に対応するための機能がマニュアルの統合です。この機能はMarkdownで書かれた複数のファイルをドキュメントに組み込むことができます。これによって,インストール方法,操作方法,サンプルなどを自由に組み込めることができます。

画像

カバレッジ

「継続性」を満たすためにドキュメントのカバレッジ機能を提供しています。カバレッジ機能とはテストカバレッジと同じように,ドキュメントが書かれるべきところにどれだけ書かれているかを確認する機能です。ドキュメントのカバレッジを可視化することで,継続的にドキュメントを保守するモチベーションに繋がると考えています。

このカバレッジ機能について一つ注意してほしいことは,かならずしもカバレッジ100%を目指す必要はないということです。あくまでもドキュメントの継続性を満たすためのものであり,どの程度のカバレッジが必要かは各開発者の判断にお任せします。

画像

画像

Lint

「正確性」を満たすためにLint機能を提供しています。Lint機能とはドキュメントがコードに対して間違っていないかを検証するための機能です。あくまでもドキュメントとコードの不一致を検証するのであって,ドキュメント自体が正しいかどうかを検証できるものではありません。今のところ,このLintが対象にするのはメソッドのシグネチャとドキュメントが一致しているかどうかだけです。

画像

静的解析

「網羅性」を満たすための静的解析機能を提供しています。静的解析機能とはドキュメントコメントが書かれていないコードからも,そのコードからわかる情報を使ってなるべくドキュメントを生成するというものです。

例えば次のようにドキュメントが一切書いていないソースコードの場合でも「Class構文によるクラスと継承」⁠デフォルト引数による仮引数の型」⁠return文による戻り値の存在」⁠テンプレートリテラルによる文字列型」を解析することで,ある程度ドキュメントを作成することができます。

export default class Foo extends Bar {
  baz(p = 'Alice') {
    return `hello ${p}`;
  }
}

テストコードの統合

「関連性」を満たすためにテストコードの統合機能を提供しています。テストコードの統合機能とはテストコード自体も有益なドキュメントと考え,テストコードとテスト対象を関連付けてドキュメントを生成するというものです。

テストコードとテスト対象を次のように関連付けると,生成されたFooクラスのドキュメントにはテストコードへのリンクが,テストコードの一覧にはテスト対象へのリンクが自動的に追加されます。

/** @test {Foo} */
describe('Foo is useful class', ()=>{
  /** @test {Foo#bar} */
  it('is useful method', ()=>{
    const foo = new Foo();
    assert(typeof foo.bar, 'function');
  });
});

画像

画像

組み込み検索

「検索性」を満たすために組み込み検索機能を提供しています。組み込み検索機能とはその名前のとおり,ドキュメント内を検索できる機能です。この組み込み検索機能はJavaScriptだけで実装されているため,サーバ側の実装は一切不要です。静的ファイルとしてWebサーバで配信する,もしくはローカルのファイルをブラウザで直接開いて検索できます。

画像

ホスティング

ドキュメントを作成したあと,どこかで公開して誰でも閲覧できるようにする必要があります。そこで手軽にドキュメントを公開できる仕組みとして,ESDoc専用のホスティングサービスを提供しています。このホスティングサービスはESDocを使用しているGitHubのリポジトリURLを登録するだけで利用できます。

画像

画像

まとめ

ドキュメントを要素と性質に構造化することで,良いドキュメントを書けるのではないかという考えを述べました。そしてその考えをもとに筆者が開発しているESDocというドキュメンテーションツールとその機能を紹介しました。このように,ドキュメントを書く技術に関してはまだまだ発展の余地があります。みなさんもより良いドキュメントを書くためにドキュメントについて考察してみるのはいかがでしょうか。より良いドキュメントはより良いソフトウェアを作ります。

なお,本稿ではドキュメントの構造を中心にお話しましたが,⁠ドキュメントとはそもそもどういうものなのか?」⁠何故ドキュメントを書くのか?」⁠良いドキュメントとは?」などの話については The Web Explorerにて掲載しています。この書籍は多数の著者による共著になっており,ESDoc以外にもWebの最先端の話が収録された書籍になりますので,興味のある方は是非ご覧ください。

著者プロフィール

丸山亮(まるやまりょう)

Cookpad株式会社所属。サービスオーナー兼エンジニアとしてサービス開発を行っている。個人ではJavaScript関係のツールを作ったり,CodeLunch.fmというポッドキャストをしている。趣味は料理と民芸食器を集めること。好きな窯は出西窯。

Twitter@h13i32maru
ブログhttp://blog.h13i32maru.jp

コメント

コメントの記入