私が現在所属しているソフトウェア グループは、最近、コードベースのドキュメント化を開始することを決定しました。彼らが採用している最初のアプローチは、組み込みのトリプル スラッシュ /// の文書化方法を使用することでした。
私たちが発見し始めた新しい問題は、doxygen を介してこれを実行した結果が、コードベースの非常に適切な表現であるということでした。タスクが正確に何をしているのかを尋ねます。
/// メソッドと doxygen を使用してコードを文書化する簡単な方法はありますか?特定の方法で実行すると、システム エンジニアリング バージョンの文書だけを含む文書を生成できます。メソッドやメンバー変数など、システム担当者を怖がらせる標準的なプログラマー向けドキュメントはありますか? 代替ソリューションの提案も大歓迎です。
これが私たちが達成しようとしていることについて少し混乱している場合は申し訳ありませんが、回答が得られたら調整できます. ありがとう.
コードを文書化している場合、それはプログラマーによって読まれると想定できます。プライベート メンバーは出力から取り除くことができます。これにより、パブリックメンバーをパブリック ドキュメントとして文書化できます。コード、つまり非開発者が使用するエンドユーザー インターフェイスをドキュメント化していない場合、コードは最適な場所ではないと思います。
これであなたの欲しいものが手に入るとは思えません。あなたが本当に望んでいるのは、システム エンジニアが使用できる優れた仕様ドキュメントと、コードがそれらの仕様に従って実行されることを検証する優れた単体テストがあることのようです。インライン コードのドキュメントは、実際にはソフトウェア エンジニア向けです。
あなたの質問で少し驚くべきことと少し恐ろしいことは、システム エンジニアが使用しなければならないシステムをソフトウェア エンジニアが作成し、ソフトウェア エンジニアがゼロから機能を作成しているということです。ソフトウェア エンジニアが機能を定義する際には、細心の注意を払う必要があります。彼らは特定の機能を実装する必要があります (その仕様は、システム エンジニアが使用するものでなければなりません)。
できることの 1 つは\page、「関連ページ」を表示する doxygen のコマンドを使用することです。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。
私たちのプロジェクトでは、基本的にプログラムを使用するすべての人がプログラムを使用してコーディングを行っているため、使用方法のドキュメントがコードと相互リンクされていると便利です。しかし、他の人が指摘したように、それは典型的なエンドユーザー文書にとって最良の解決策ではないかもしれません.