公開用のドキュメント（外部に公開するインターフェースの仕様に対するドキュメント）に関するツールはそこらへんに色々転がっているからどうでも良い．今，自分は保守用のドキュメント（実装詳細に関する様々な注釈・覚書等）に関するツールを探している．けれども自分のニーズに応えてくれそうなツールがなかなか見つからない．特に自分の要望としては，きれいな数式をコードのコメントとして出力して実際のコードと並列に見比べられるような出力が可能なツールが欲しい，というもの．
こんな感じのコードを出力してくれるツールが理想．
//を計算する
z = sqrt(x * x + y * y);
なぜこれが欲しいかというと，特に数値計算において，数式での表現と実際のコード上の表現の乖離を埋めたいのだ．いや数値計算なんてプログラム上での表現と実際にやってることがだいたい対応するじゃん，と思われるかも知れないけれど，むしろなまじっか表現が近いために，きちんと形式的な（数式の上での）表現がどうプログラム上の表現に対応しているかを表明しておかないと無用な混乱を生むのだ．
Doxygenはコードのannotationに気軽に数式を埋め込めるけれど，その数式を実際のコードと並行した形で表示することはできないのだよにゃ〜．現時点での最大の不満．
＃とゆ〜か，annotateしたいコード片を関数にまとめて，その関数に対して公開用のドキュメンテーションツールでannotateして，それを保守用ドキュメントとして代用すれば良いのか．とゆ〜か，ドキュメンテーションツールというのはそういう風に使えば良いのか．そ〜かそ〜か．
[English]Documentation for Maintenance
There are many tools to create documents for publification. What I'm looking for now is a tool to create documents for maintenance. But, I have not found one which meets my need yet. I focus an feature to output formula as comments parallel to actual code.
A tool which can output such code above may completely meet my needs.
// Calculate
z = sqrt(x * x + y * y);
Why I need such tools? Because, especially in numerical calculation, I want to bridge the gap between mathematical descriptions and descriptions on actual code. One may say that programs roughly correspond to mathemarical descriptions in numerical calculation. But, such similariry creates confusion, so it is necessary to document code clearly.
Doxygen allows us to write formula in documents easily but cannot output the formula parallel to code. It is my biggest complaint right now.
#Ah, ...
