手抜き英文ドキュメントコメント自動生成ツールのAtomineer Pro DocumentationとDoxygenでGithubのドキュメントページ生成
手抜き英文ドキュメントコメント自動生成ツールは、無償版はGhostDocとかが有名ですが、商用の有償版ならAtomineer Pro Documentationを押しです。
ちなみに、商用だとGhostDoc/GhostDoc Proの方が高いので、Atomineer Pro Documentationの方がお得感はあります。
Atomineer Pro Documentation for Visual Studio (2015,2013,2012,2010,2008,2005)
SubMain / GhostDoc - Painless Help Documentation
「コードがすべて!!簡単なインテリセンスのコメントさえ出ればよい・・・」
そんな人にこそ、手抜き英文ドキュメントコメント自動生成ツールがお勧め。
「日本語の方が分かりやすい？」
「国際化対応したくて日本語コメントを翻訳した時の敗北感は半端なくない？」
「スペルミス以前に、文法的におかしな命名ミスほど痛いものはないよね？」
自分は、ルールだから仕方なくコメントを付ける目的よりも、認識子にそれなりに相応しい名前を付けるというのを目的に使っている。
この手のツールは、Pascal caseやcamel caseの認識子や、言語構文などの情報から、英文で自然言語のコメントを生成するツールだと思われるので、認識子の命名が国際的に通じるものかとの判断は、自然言語に変換できるか否かに、ほぼ等しいはずだから・・・
あとは、追加のコメントをゴリゴリ書くか？という話だけど、インテリセンスやオブジェクトブラウザに表示されない情報の利用率は低いので、命名が妥当なら取りえずソースファイルから一瞬でドキュメントコメントが生成できるというのは非常にうれしい。
特に、インテリセンスのみ重視なら、summaryとparam、それにreturnsがあれば十分だが、それはデフォルトコメントでほぼOK。ダメなら、もっと相応しい命名があるってこと。
また、Atomineer Pro Documentationは、対応言語や対応ドキュメントコメントフォーマットが豊富なので、C#、VB.NET、C++/CLI以外も操っている人には最適ではないかと。
日本代理店がないのが残念です。銀行口座がないと商社経由で購入して手数料が高いので・・・
2つの違い
- 対応IDE
| GhostDoc | Atomineer Pro Documentation | |
|---|---|---|
| VS2015 | X | X |
| VS2013 | X | X |
| VS2012 | X | X |
| VS2010 | X | X |
| VS2008 | X | X |
| VS2008 | X | X |
| VS2005 | X | |
| Atmel Studio 5 & 6 | X |
- 対応言語
| GhostDoc | Atomineer Pro Documentation | |
|---|---|---|
| C# | X | X |
| VB.NET | X | X |
| C++/CLI | X | X |
| C/C++ | X | |
| Javascript | X | X |
| Typescript | X | |
| Java | X | |
| python | X | |
| PHP | X | |
| UnrealScript | X |
- 対応ドキュメントコメントフォーマット
| GhostDoc | Atomineer Pro Documentation | |
|---|---|---|
| XML Documentation | X | X |
| Doxygen | X | |
| JavaDoc | X | |
| JSDoc/JSDuck | X | |
| Qt | X |
ドキュメントジェネレータの定番はDoxygen
C#, C++/CLI, VB.NETなどは、XML Documentationスタイル。
などと使い分けることが出来るが、Doxygenはソースファイルを直接処理できるので、C++もXML Documentationスタイルで記述しても問題ない。
Atomineer Pro Documentationの設定
最初に、一括、もしくは言語ごとに、ドキュメントコメント形式やその基本設定を行う。
XML Documentationで良ければ、一括で設定してしまえばよい。
次に、細かなフォーマット方法を指定する。
こだわりが出てくる部分にマークを付けてみたが、改行やインデント方法などを、いろいろなパターンで選択できる。
ユーザ名や日付形式は変更しておいた方がよい。
StyleCop対応等もここで行う。
テンプレートをカスタマイズしたり、企業名などを設定したり、辞書関係もカスタマイズ可能。
気の利いた機能も豊富だが、時には余計なお世話となることも多いので、その辺は「その他」で結構カスタマイズが効く。
使い方は、簡単で一番多いのは、ファイル一括か、コメントを入れたい部分で個別挿入。
ちなみに、ソリューションやプロジェクト単位もあるが、試用版では試せない。
Github Pagesの作成
ドキュメントコメントが挿入出来たら、コミットして、githubのマスターにも反映する。
終わったら、Github Pagesを作成する。
Creating Pages with the automatic generator - User Documentation
取りあえずデザインとかはなんでもいい。Doxygenの出力内容に差し替えるので・・・
Pageが出来たら、ローカルにpullする。
そのままだと使いにくいので、gh-pagesという特殊なbranchが出来ているのでsubmodule化する。
Doxygen を github-pages にあげるのをお気楽にやる方法 - tokuhirom's blog
TortoiseGitとかだと、Submodule Addとかいうメニューがあるのでそれでやる。
リポジトリのdocsにサブモジュールができるが、Githubで作成されたテンプレートは要らないので削除してコミットしておく。 (.gitは消さないで!!)
Doxywizardでドキュメント生成
慣れないうちはGUIで設定して、ドキュメント生成を行うと良い。
好みもあるが、ドキュメント生成単位はソリューション単位や、githubのリポジトリ単位が良い。
出力先は、サブモジュールのdocsだが、出力タイプによりサブフォルダが切られて、Github Pagesのindex.htmlの位置が変わるのでここでは選ばない。
C#の設定にして、あとはお好み。
htmlでも、ナビゲーション付けたりいろいろ出来る。
図は、ビルトイン方式か、GraphVizが選べる。
拡張メソッドとかあるなら、staticメンバーの出力は必須。
ライブラリ開発者なら、privateやinternalもフォローしておきたい。
ファイルのリストとかも出来るので、不要なものは除外しておく。
出力先のdocsフォルダはここで選んでおく。
設定が終わったら、生成してプレビュー。気に入らなかったら、カスタマイズしてください。
OKならサブモジュールでコミットして、githubへpushしてください。
Github PagesのURLはSettingsに表示されています。
Readmeなどにリンクを張りましょう。
Readmeの先頭のリンクからご確認ください。
PS
Doxygen以外にもDocFxというのもあるらしいですね。今度試してみたいですね。
DocFX - .NET向けAPIドキュメントを生成するツール - ぷろじぇくと、みすじら。 - Misuzilla.org
追記
Github Pagesでは、Doxygenが生成するアンダースコアで始まるソースコードのhtmlは表示できないみたいです。
一応、サポートに連絡しました。
追記2
Files that start with an underscore are missing - User Documentation
