読者です 読者をやめる 読者になる 読者になる

tmori3y2のブログ

主にWindowsのプログラムなど

手抜き英文ドキュメントコメント自動生成ツールのAtomineer Pro DocumentationとDoxygenでGithubのドキュメントページ生成

Atomineer Pro Documentation Doxygen XML Documentation

手抜き英文ドキュメントコメント自動生成ツールは、無償版は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.NETC++/CLI以外も操っている人には最適ではないかと。

日本代理店がないのが残念です。銀行口座がないと商社経由で購入して手数料が高いので・・・

2つの違い
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

www.stack.nl

www.doxygen.jp

  • 対応ドキュメントコメントフォーマット(インプット)

C#, C++/CLI, VB.NETなどは、XML Documentationスタイル。

C++は、JavaDoc/Qtスタイル。

などと使い分けることが出来るが、Doxygenはソースファイルを直接処理できるので、C++XML Documentationスタイルで記述しても問題ない。

Atomineer Pro Documentationの設定

f:id:tmori3y2:20160622223703p:plain

最初に、一括、もしくは言語ごとに、ドキュメントコメント形式やその基本設定を行う。

XML Documentationで良ければ、一括で設定してしまえばよい。

f:id:tmori3y2:20160622223717p:plain

次に、細かなフォーマット方法を指定する。

こだわりが出てくる部分にマークを付けてみたが、改行やインデント方法などを、いろいろなパターンで選択できる。

f:id:tmori3y2:20160622223954p:plain

ユーザ名や日付形式は変更しておいた方がよい。

StyleCop対応等もここで行う。

f:id:tmori3y2:20160622224010p:plain

テンプレートをカスタマイズしたり、企業名などを設定したり、辞書関係もカスタマイズ可能。

f:id:tmori3y2:20160622224901p:plain

気の利いた機能も豊富だが、時には余計なお世話となることも多いので、その辺は「その他」で結構カスタマイズが効く。

使い方は、簡単で一番多いのは、ファイル一括か、コメントを入れたい部分で個別挿入。

ちなみに、ソリューションやプロジェクト単位もあるが、試用版では試せない。

Github Pagesの作成

ドキュメントコメントが挿入出来たら、コミットして、githubのマスターにも反映する。

終わったら、Github Pagesを作成する。

Creating Pages with the automatic generator - User Documentation

取りあえずデザインとかはなんでもいい。Doxygenの出力内容に差し替えるので・・・

Pageが出来たら、ローカルにpullする。

そのままだと使いにくいので、gh-pagesという特殊なbranchが出来ているのでsubmodule化する。

d.hatena.ne.jp

Doxygen を github-pages にあげるのをお気楽にやる方法 - tokuhirom's blog

TortoiseGitとかだと、Submodule Addとかいうメニューがあるのでそれでやる。

f:id:tmori3y2:20160623013137p:plain

リポジトリのdocsにサブモジュールができるが、Githubで作成されたテンプレートは要らないので削除してコミットしておく。 (.gitは消さないで!!)

Doxywizardでドキュメント生成

慣れないうちはGUIで設定して、ドキュメント生成を行うと良い。

f:id:tmori3y2:20160623015539p:plain

好みもあるが、ドキュメント生成単位はソリューション単位や、githubリポジトリ単位が良い。

出力先は、サブモジュールのdocsだが、出力タイプによりサブフォルダが切られて、Github Pagesのindex.htmlの位置が変わるのでここでは選ばない。

f:id:tmori3y2:20160622233250p:plain

C#の設定にして、あとはお好み。

f:id:tmori3y2:20160622233446p:plain

htmlでも、ナビゲーション付けたりいろいろ出来る。

f:id:tmori3y2:20160622233634p:plain

図は、ビルトイン方式か、GraphVizが選べる。

f:id:tmori3y2:20160622233804p:plain

拡張メソッドとかあるなら、staticメンバーの出力は必須。

ライブラリ開発者なら、privateやinternalもフォローしておきたい。

f:id:tmori3y2:20160622233949p:plain

ファイルのリストとかも出来るので、不要なものは除外しておく。

f:id:tmori3y2:20160623015723p:plain

出力先のdocsフォルダはここで選んでおく。

f:id:tmori3y2:20160623015804p:plain

設定が終わったら、生成してプレビュー。気に入らなかったら、カスタマイズしてください。

OKならサブモジュールでコミットして、githubへpushしてください。

Github PagesのURLはSettingsに表示されています。

Readmeなどにリンクを張りましょう。

github.com

Readmeの先頭のリンクからご確認ください。

PS

Doxygen以外にもDocFxというのもあるらしいですね。今度試してみたいですね。

DocFX - .NET向けAPIドキュメントを生成するツール - ぷろじぇくと、みすじら。 - Misuzilla.org

追記

Github Pagesでは、Doxygenが生成するアンダースコアで始まるソースコードのhtmlは表示できないみたいです。

一応、サポートに連絡しました。

追記2

Files that start with an underscore are missing - User Documentation

取り敢えずスマホで .nojekyllをgithubで作ってcommitしときました。