JSDoc 3 用のプラグインをまとめてみた post

世の中には「ソースコードが仕様書」という話を聞いたりします。

まあ、ソースコードと仕様書を同期して更新するなんて大変ですよね。

そこで、誰が考えたのか、まさにソースコードから仕様書を作るツールが DoxygenJSDoc などになります。

先に上がった JSDoc は JavaScript 専用のドキュメント生成ツールですが、どうやらプラグイン機能があるとのことで、標準添付のプラグインの情報すら日本語のものはなさそうだったので簡単に調べてまとめてみました。

プラグインの使い方

基本的には Use JSDoc: About JSDoc plugins に書かれているように、JSDoc の設定ファイル jsdoc.json

{
    "plugins": ["plugins/shout"]
}

みたいな感じに書けば利用可能となるようです。

自分で作りたい場合は、同じく Use JSDoc: About JSDoc pluginsEvent HandlersTag Definitions などを見ながら作ればいいのではないかと思います。

標準添付(非実用プラグイン)

標準添付されているプラグインの中には、サンプルや開発用のプラグインも含まれています。

commentConvert.js

beforeParse イベントのサンプルプラグイン。

これは、非実用的なプラグインのようです。

shout.js

newDoclet イベントのサンプルプラグイン。

これは、非実用的なプラグインのようです。

eventDumper.js

コンソールにパーサーイベントに関する情報をダンプするプラグイン。

これは、開発に利用するための非実用的なプラグインのようです。

標準添付(実用プラグイン)

標準添付された様々な機能を持つプラグイン

commentsOnly.js

JavaScript 以外の言語で書かれたソースに含まれる JSDoc 形式のコメント以外を削除することで、ドキュメント化することができるようになるプラグイン。

escapeHtml.js

ドキュメント中に含まれる HTML タグをエスケープするプラグイン。

markdown.js

Markdown 記法で書かれたコメント内のテキストを HTML に変換できるようにするプラグイン。

Use JSDoc: Using the Markdown plugin に使い方が載っています。

overloadHelper.js

自動的にオーバーロード関数やメソッドの長い名前に署名のような文字列を追加するプラグイン。

partial.js

@partial FILENAME とすることで、FILENAME をそこに読み込むプラグイン。

railsTemplate.js

.erb ファイル (Rails の HTML テンプレートファイル) から Rails のテンプレートタグを除去するプラグイン。

sourcetag.js

@source { "filename": "sourcetag.js", "lineno": 13 } のような感じで、ファイルの現在位置に関するメタ情報を更新できるプラグイン。

summarize.js

説明が不足している場合に要約を自動生成するプラグイン。

underscore.js

_ から始まる JSDoc コメントの全ての属性を private に変更するプラグイン。

npm に登録されているもの

ub-jsdoc

npm ページ:ub-jsdoc

godoc にインスパアされたテーマ&プラグイン。

jsdoc-codesnippet

npm ページ:jsdoc-codesnippet

名前をつけたコードスニペットをドキュメントに含めることができるようになるプラグイン。

jsdoc-vue

npm ページ:jsdoc-vue

*.vue ファイル (Vueify 用のファイル) を解析できるようにするプラグイン。

jsdoc-plugins

npm ページ:jsdoc-plugins

いろんなタグを実装したプラグイン。

jsdoc-babel

npm ページ:jsdoc-babel

JavaScript ファイルの解析前に Babel で事前処理を行うプラグイン。

jsdoc-riot

npm ページ:jsdoc-riot

Riot タグファイルのサポートを追加するプラグイン。

jsdoc-ignore-future

npm ページ:jsdoc-ignore-future

jsdoc-escape-at

npm ページ:jsdoc-escape-at

コメント中の @ をエスケープするプラグイン?

jsdoc-plugin-named-defaults

npm ページ:jsdoc-plugin-named-defaults

引数のデフォルト値をコード中から拾ってくるプラグイン?

jsdoc-jsx

npm ページ:jsdoc-jsx

(Facebook の) JSX ファイルのサポートを追加するプラグイン。

jsdoc-plugin-strip-outer-iife

npm ページ:jsdoc-plugin-strip-outer-iife

一番外側の IIFE (Immediately-invoked function expression:即時実行関数式) を除去するプラグイン。

jsdoc-bem

npm ページ:jsdoc-bem

BEM の要素のサポートを追加するプラグイン?

bouquet

npm ページ:bouquet

有用なプラグインを集めたプラグイン。

参考


 /  変更履歴  /  Permalink  /  このエントリーをはてなブックマークに追加
カテゴリ: まとめ  /  タグ: JSDoc, JavaScript