こんにちわ、DeNA San Francisco の渋川と申します。エンジニアブログには初登場です。

JavaScriptのソースコードからAPIドキュメントを生成するツールには何種類かありますが、日本語の書籍やウェブサイトでも情報が得やすいこともあって、JSDocの系統が幅広く使われています。Google Closure Compilerも、JSDocを拡張したドックコメントをアノテーションとして読み込んで最適化します。

JSDocは長い期間メンテナンスされているオープンソースプロダクトです。初代はPerlで書かれたJSDoc 1です。これはすでにリポジトリも削除されています。現在最も使われているのが JSDoc Toolkit (JSDoc 2) です。弊社の ngCoreのドキュメント でも使用しています。

ただ、これも現在は機能追加を停止していて、後継プロダクトの JSDoc 3 が開発されています。今年の3月に入ってJSDoc 3自体のドキュメントもほぼ整備されたため、今後は実践で使われることが多くなりそうです。

JSDoc Toolkitと比較すると、JSDoc 3はタグが整理されていたり、JavaScriptで多様されるイディオムを表現するための新しいタグが追加されていたりします。以前も拡張機能を使ってタグを増やすこともできましたが(ngCoreのドキュメントのコールバックの説明が独自拡張のタグ)、はじめからコールバックの記述もできるようになっていたり、コーディングの意図を伝える表現力は以前よりも増しています。

JSDoc 3は、タグが整理されたことによって、JSDoc Toolkitとは後方互換性がなくなっています。タグによって名前や意味が変わったり、パラメータが変わったりしています。JSDoc 3自体のドキュメントには互換性に関するまとまった説明がなかったため、業務で開発しているJavaScriptのコードのドキュメントをJSDoc ToolkitからJSDoc 3に切り替えた時は、新旧のドキュメントを見比べて手探りで移行しました。このエントリーではその時の経験を元に、JSDoc ToolkitのコメントをJSDoc 3にどのように対応させればいいのかを紹介します。

JSDoc 2とは意味が異なるタグ

• @exports

  このタグは @typedef タグに書き換えてください。 @exports タグは、モジュールを説明するタグへと変更されました ( @module , @exports のドキュメント参照)。

• @event

  JSDoc 2では @event タグは関数の一種(@function タグと同じ文法を持つ)タグで、イベントを発行する関数であることをマークします。JSDoc 3では @event はイベントオブジェクトを説明するために利用されるタグになりました。JSDoc 2の@eventと置き換えるタグとして、JSDoc 3では @fires タグという新しいタグを提供しています。

• @class

  JSDoc 2の @class タグはJSDoc 3の @constructor タグへと改名されました。新しい @class タグのパラメータはJSDoc 2とは意味が変わり、クラスの説明ではなくクラス名を表すようになりました。クラスの説明を書く時は @classdesc タグを使用してください。

• @fileOverview

  タグの名前が変わりました。 @file (もしくはエイリアスの @fileoverview, @overview)に書き換えてください。

• @member

  @memberタグは@memberOfのエイリアスでしたが、JSDoc 3ではJSDoc 2の@fieldと同じ意味になりました。 @memberof に書き換えてください。

• @field

  タグ名が @member に変わりました。

• @memberOf, @methodOf, @fieldOf

  タグ名がcamelCaseから、小文字の @memberof に変わりました。また、@methodOf (@method + @memberOf)と@fieldOf (@field + @memberOf)はJSDoc 3ではサポートされません。それぞれのタグを@memberof, @method + @memberof, @member + @memberofに書き換えてください。

• @constructs

  JSDoc 2では、@constructsタグには引数がなかったため、コンストラクタ関数の説明を後ろに続けて書いても問題はありませんでした。JSDoc 3では @constructs はクラス名を引数に取るようになりました。もしタグの後ろに説明が入っている場合は改行を入れてください。

• @name

  JSDoc 3は名前のみを変えるタグとして @alias タグを提供しています。 @name タグはソースコードから得られる情報をすべて無視した上で名前を指示するタグです。もし要素の名前だけを変えたい場合には@aliasタグが推奨されます。@nameタグは(実行時に動的に作られるような)仮想の項目に使うようにしましょう。

• @public

  JSDoc 3では、 @public タグはシンボルのスコープを変更しなくなりました。スコープを変更する場合は、 @inner , @instance , @static , @global タグを使用してください。

• @author

  JSDoc 3では、 @author が拡張されて、著者名の後にあるEメールアドレスをパースするようになりました。HTMLを使って"mailto:“へのリンクを作成する必要はありません。

• メタタグ

  JSDoc 3ではサポートされません。

JSDoc 3の便利な新機能

JSDoc 3はドキュメントの品質を向上させる魅力的な新機能を提供しています。

長文の説明

JSDoc 3は単にソースコードから生成されるAPIドキュメントにくわえて、長文の説明をインポートする機能を持っています。

README.mdのインポート

JSDoc 3は、 README.md をインポートして、トップページのコンテンツにすることができます。 ここ に説明があります。

チュートリアル

HTMLかMarkdownで書かれた長文の説明ページを追加することができます。 ここ に説明があります。

型仕様

JSDoc 3では現在、型仕様のパースの機能が改修中です。最終的にはClosure Compilerと同じ書式を理解できるようになるのを目標としています。現在はそこまで完成はしていませんが、以前よりもきちんと表現できるようになっています。 @type タグのページに説明があります。

新しい型に対する説明

JavaScriptは非常に柔軟な言語です。文法の上に、さまざまなイディオムが考案されて使われています。JSDoc 3はさまざまな新しいJavaScriptのイディオムをサポートしています。これらのタグを使えば、コードの意図をより明確に伝えることができます。

• コールバック関数

  JSDoc 3は @callback タグを使うことで、コールバック関数をカスタム型として定義することができるようになりました。コールバック関数に設定すべきパラメータや、どのような型を想定しているのかが記述できるようになりました。

• 列挙型 / 定数

  JSDoc 3では、列挙型の定数テーブル( @enum タグを使用)を、JSDoc 2(要素ごとに@memberタグを使用)よりも簡単に定義できるようになりました。

• Mix-in

  Mix-inは動的言語では人気のあるコンセプトです。JSDoc 3では @mixin と @mixes タグを使うことで、このイディオムのドキュメントを作成することができます。

• 仮想メンバー

  @abstract タグを使うことで、そのメンバーが子クラスで実装されたり、オーバーライドされるべきであるということを伝えることができます。

• 読み込み専用メンバー

  JSDoc 2も、JSDoc 3も、定数メンバーを説明するための @constant (あるいはエイリアスの@const)タグをすでにサポートしています。JSDoc 3ではこれに加えて、getterメソッドでも利用できる @readonly タグをサポートしました。

• 異なるスコープを持つメンバー

  JSDoc 3では要素のスコープを説明するタグが追加されました: @instance (new), @global (new), @inner , @static

• モジュール機能

  JavaScriptは幅広い環境で使われています。環境によってはモジュール機能をサポートしていたり、特別なライブラリを利用するケースもあります。

  • モジュール

    JSDoc 3ではCommonJSスタイル、node.jsスタイル、RequireJSスタイルのモジュールをサポートする、モジュール機能が追加されました。 @module , @exports タグのドキュメントを参照してください。

  • 外部モジュール

    JSDoc 3では、外部モジュールや組み込みの要素を説明するための @external タグをサポートしています。この機能を使って定義した外部のクラスや型は、ベースクラスとして使ったり、パラメータとして使うことができます。

リンクテキストのフォント

シンボル名へのリンクなど、リンクテキストを等幅フォントで出力したいケースはよくあります。JSDoc Toolkitのように <code>{@link Symbol}</code> と書く必要はありません。JSDoc 3では、リンクテキストを等幅フォントにする機能を提供してます:

• {@linkcode Symbol}

  等幅で出力

• 設定ファイルの template.monospaceLinks オプションあるいは templates.cleverLinks オプション

  ドキュメント全体のフォント設定に影響を与えるオプションです。前者は常に等幅、後者はコード中へのシンボルのリンクのみを等幅にします。

Markdownサポート

Markdownで説明を記述することができます。チュートリアルやREADMEは設定を変えることなく利用することができますし、Markdownプラグインを入れると、ドックコメント内の説明にも利用することができます。

より厳密なドキュメントを書くための新しいタグ

• @summary タグ

  ドックコメントに1行のサマリーの説明を追加するタグ。

• @kind タグ

  オブジェクトの種類を明示(通常は不要)するタグ。

• @variation タグ

  同名のメソッドや要素に対して、接尾辞を追加することでリンク時に区別できるようにするためのタグ。

• @todo タグ

  未実装部分を説明する時に使うタグ。

• @copyright タグ

  著作権について説明する時に使うタグ。

• @license タグ

  ライセンスについて説明するときに使うタグ。

JSDoc 3プロジェクトへの貢献

JSDoc 3を使わせてもらうだけでは何なので、このエントリーの元の原稿(英語)をJSDoc 3のプロジェクトのドキュメントに対してpull requestとして出しています。ついでにドキュメントの間違っているところを何件か報告したりもしました。

ドキュメントの日本語訳も現時点で95%ほど終わっています。移行ガイドがマージされたらどこかで公開しようと思っています。どうぞお待ちを！

参考リンク

• JSDoc 3ドキュメント(英語)
• JSDoc 3プロジェクトページ(github)
• JSDoc 3ドキュメント翻訳(Transifex)