見通しの良い開発ドキュメントを。自動生成ツールまとめ
ドキュメントを構築する時に便利なツールをまとめました。参考となる資料ページも紹介していますので、是非ご覧下さい。
Sandcastle Help File Builder
Sandcastle Help File Builderは、Sandcastleを利用するためのWindows製のGUIツールです。Sandcastle自体はJavaDocの.NET版と考えて良いでしょう。本ツールはMicrosoft社よりオープンソースとして公開されています。
コマンドラインからでもヘルプファイルを作成することが可能ですが、このツールを利用するほうが一般的でしょう。
Sandcastle – Documentation Compiler
技術文書のためのマークアップ言語 DocBook
DocBookは技術文書のためのマークアップ言語として定義されました。
歴史も長く、現在のDocBookのバージョンは5.xが主流となっています。 文書はXMLで記述しますので、このオリジナルから、HTML、EPUB、PDFなどいろいろなフォーマットで出力できます。
変換はLnix系OSならば xsltproc コマンドで行うと良いでしょう。他にもJavaなどの各言語でも変換ツールがありますので興味のある方は調べてみてはいかがでしょうか。
Python製ドキュメンテーションビルダー SPHINX
SphinxはPython製のドキュメントジェネレータです。Windows、MacOSX、Linuxでサポートされています。 Wikiに似たマークアップとディレクティブを利用してドキュメントを作成し、コマンドラインからドキュメントを生成します。 ドキュメントはHTML、PDF、EPUBと主要なフォーマットは押さえているようです。
Python製とあって利用はPythonプロジェクトが多いと思いますが、他の言語でも特に問題になることはないでしょう。
Sphinxをはじめよう — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会
Re:VIEW
Re:VIEWはRuby言語で記述されたドキュメントジェネレーターです。 Linux/Unix 互換システムで動作します。Mac OS X および Windows Cygwin でも動作可能です。 変換フォーマットは、プレーンテキスト、LaTeX、HTML、XMLやEPUBをカバーし、InDesignにも対応したようです。
マークアップは「ASCIIのEWB」を基本としながら、一部に RD や各種 Wiki の文法をとりいれて簡素化しています。
PHPプロジェクト用のドキュメントジェネレーター ApiGen
ApiGenはPHP製のドキュメントジェネレータです。PHPのJavaDoc版と考えて頂ければよいでしょう。コメントブロックをドキュメントに生成するツールです。インストールには、PHP5.4以上とpearが必要になります。
PHPプロジェクト用のドキュメントジェネレーター phpDocumentor
phpDocumentorもPHP製のドキュメントジェネレータです。多くの言語系ドキュメントジェネレーターと同じく、コメントブロックをドキュメント生成します。テンプレートも多めで好みのものを選べそうです。
先出のApiGenとどちらが良いかはプロジェクトによると思いますが、インストールコストも多くはかかりませんし、両方試してみると良いでしょう。
JavaScript用のドキュメントジェネレーター @use JSDoc
JSDocはJavaScript用のドキュメントジェネレーターです。アノテーションベースでコメントブロックをドキュメント化するのは、JavaDocと同様です。
利用の際にはJDKおよびMozilla Rhinoが必要です。
何かと見通しが悪くなってしまうJavaScriptコードですが、クラスやパブリックメンバーをタグを使って説明を書く習慣をつけることは、後々の開発で役に立つでしょう。
Ruby製ドキュメントジェネレーター
RDocはRuby用のドキュメントジェネレーターです。RubyコメントからJavaDocと同様にソースを解析したのち、HTMLとしてドキュメントを生成します。
カスタムのHTMLテンプレートでドキュメントを生成することも可能です。
マークアップも独自の物を利用していますが、基本的なサンプルを見ればすぐに使いこなせるでしょう。
まとめ
日本の開発現場ではドキュメントの生成やメンテナンスに苦労している方が多いように思います。アプリケーション開発と同程度の労力とまでは言いませんが同じくらいの工数をかけているのではないでしょうか。
とはいえ、コストを下げるためにおろそかになったり、システムの実運用と乖離していると、引き継ぐ場合にコストが掛かりすぎて困る場合があります。今回紹介したツールなどを使い、極力自動生成を行い運用すれば、少しでもプロジェクトのコストが抑えられるのではないでしょうか。
hifive開発者ブログ 
コメントは受け付けていません。