C＃NON-Programmerのソース内ドキュメント生成

Question

私が現在取り組んでいるソフトウェアグループは、最近、私たちのコードベースの文書化を開始することに決めました。彼らが取り組んできた初期のアプローチは、文書化の三重スラッシュ///の方法を使用することでした。

私たちが見つけ始めた新しい問題は、これをdoxygenで実行した結果、コードベースが非常にうまく表現されたことですが、プログラマーが使用するためには、このドキュメントをシステムエンジニアが読むことができる仕事が正確に何をしているのかを尋ねることがよくあります。

私たちのコードを///メソッドとdoxygenを使って簡単に実行できるのであれば、システムエンジニアリングバージョンのドキュメントを含むドキュメントを生成することができます。メソッドやメンバ変数などのシステムの人を怖がらせる標準的なプログラマドキュメントの余計なものはありますか？代替ソリューション提案も歓迎されます。

私たちが達成しようとしていることについて少し混乱しているのであれば、私は申し訳ありませんが、私は応答が入ると調整できます。 ありがとうございます。

Answer 1

「doxygen」の\pageコマンドを使用すると、「関連ページ」が表示されます。 doxygenによって処理される拡張子を持つテキストファイルを作成し、そこにコメントを入れます。 （私は.docを使用していますが、Word文書との混乱を避けるために別のものに変更したい場合があります。また、これらのファイルをdocsrcという共通のディレクトリに入れて1か所に置いています）。ドキュメントの別々のセクション。

/*!  
\page foobar Foobar calculation 

I am using the procedure outlined in the bla bla note to estimate 
the foobar in our baz. Lorem ipsum dolor... 

\section step1 1. Estimation of the foobar-efficiency of the baz system. 

\author jdm 
*/ 

その後、\ref foobarまたは\ref step1のページへのリンクやセクションを作成することができます。

私たちのプロジェクトでは、基本的にプログラムを使用するすべての人が同じコードを使用しています。そのため、コードとクロスリンクされた使用方法のドキュメントを用意するのは良いことです。しかし、他の人たちが指摘しているように、典型的なエンドユーザ文書のための最良のソリューションではないかもしれません。

Answer 2

私はこれがあなたが望むものを得ることはないと思います。システムエンジニアが使用できる優れた仕様書を用意し、その仕様に従ってコードが実行されることを検証する優れた単体テストを実際に望むように思えます。インラインコードのドキュメントは、ソフトウェアエンジニアのためのものです。

あなたの質問に少し驚くようなことは、ソフトウェアエンジニアがシステムエンジニアが使用しなければならないシステムを作成していることと、ソフトウェアエンジニアが何の機能も作っていないことです。ソフトウェアエンジニアによって機能が定義されていることに非常に注意する必要があります。特定の機能を実装する必要があります（また、その仕様はシステムエンジニアが使用するものでなければなりません）。

Answer 3

コードを文書化している場合は、それがプログラマによって読まれると想定できます。プライベートメンバーは出力から削除することができ、公開メンバーを公開ドキュメントとして文書化することができます。コードを文書化していない場合、つまり開発者以外のユーザーが使用するエンドユーザーインターフェイスの場合は、そのコードが最適な場所であるとは思われません。