内部ライブラリのdoxygenコメントブロックを配置する場所-HまたはCPPファイル内？[閉まっている]

常識では、Doxygenコメントブロックは、クラス、構造体、列挙型、関数、宣言があるヘッダーファイルに配置する必要があります。これは、ソースなしで配布されることを意図したライブラリ（ヘッダーとオブジェクトコード付きのlibのみ）の健全な議論であることに同意します。

しかし...私は、会社の内部（または私自身のサイドプロジェクト）のライブラリを開発するときに、その完全なソースコードで使用される、まったく逆のアプローチを考えていました。私が提案するのは、ヘッダーで宣言されたクラスと関数のインターフェースを混乱させないために、実装ファイル（HPP、INL、CPPなど）に大きなコメントブロックを配置することです。

長所：

• ヘッダーファイルの乱雑さが減り、追加できるのは関数の分類のみです。
• たとえばIntellisenseが使用されるときにプレビューされるコメントブロックは衝突しません-これは、.Hファイルに関数のコメントブロックがあり、同じ.Hファイルにそのインライン定義がある場合に観察された欠陥です。 .INLファイルから含まれています。

短所：

• （明白なもの）コメントブロックは、宣言があるヘッダーファイルにはありません。

それで、あなたは何を考え、そしておそらく提案しますか？

ドキュメントを、人々がコードを使用して作業しているときに読み書きできる場所に置きます。

クラスのコメントはクラスの前にあり、メソッドのコメントはメソッドの前にあります。

それは物事が維持されていることを確認するための最良の方法です。また、比較的に傾くと回避あなたのヘッダファイルを保持感動方法のドキュメントを更新する人々の問題は、ヘッダーが汚いことを原因と再構築をトリガします。私は実際に人々が後でドキュメントを書くための言い訳としてそれを使うことを知っています！

名前は複数の場所に文書化できるという事実を利用したいです。

ヘッダーファイルで、メソッドの簡単な説明を記述し、そのすべてのパラメーターを文書化します。これらのパラメーターは、メソッド自体の実装よりも変更される可能性が低く、変更される場合は、関数プロトタイプを変更する必要があります。 。

実際の実装の横にあるソースファイルに長い形式のドキュメントを配置しているので、メソッドの進化に応じて詳細を変更できます。

例えば：

mymodule.h

/// @brief This method adds two integers.
/// @param a First integer to add.
/// @param b Second integer to add.
/// @return The sum of both parameters.
int add(int a, int b);

mymodule.cpp

/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// @TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
  return b + a;
}

ヘッダーにコメントがあることは、コメントが変更された場合、クラスのすべてのユーザーを再コンパイルする必要があることを意味します。大規模なプロジェクトの場合、コーダーは、すべてを再構築するために次の20分間を費やすリスクがある場合、ヘッダーのコメントを更新する傾向が少なくなります。

そして、あなたはhtmlドキュメントを読むべきであり、ドキュメントのコードを閲覧しないことになっているので、コメントブロックがソースファイルで見つけるのがより難しくなることは大きな問題ではありません。

ヘッダー： ファイルを見るときに他の「ノイズ」が少なくなるため、コメントが読みやすくなります。

出典： コメントを見ながら読むことができる実際の関数があります。

ヘッダーでコメント化されたすべてのグローバル関数とソースでコメント化されたローカル関数を使用するだけです。必要に応じて、copydocコマンドを含めて、ドキュメントを何度も記述せずに複数の場所に挿入することもできます（メンテナンスに適しています）。

ただし、簡単なコマンドで結果を別のファイルのドキュメントにコピーすることもできます。例：-

私のfile1.h

/**
 * \brief Short about function
 *
 * More about function
 */
WORD my_fync1(BYTE*);

MY file1.c

/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}

これで、両方の関数について同じドキュメントが得られます。

これにより、コードファイルのノイズが減ると同時に、ドキュメントが1か所で記述され、最終出力の複数の場所に表示されます。

通常、インターフェース（\ param、\ return）のドキュメントは.hファイルに、実装（\ details）のドキュメントは.c / .cpp / .mファイルに配置します。Doxygenは、関数/メソッドのドキュメントのすべてをグループ化します。

すべてをヘッダーファイルに入れました。

私はすべてを文書化しますが、一般的には公開インターフェースのみを抽出します。

プログラミングにQtCreatorを使用しています。非常に便利なトリックは、ヘッダーファイルの宣言を取得する関数またはメソッドをCtrlキーを押しながらクリックすることです。

メソッドがヘッダーファイルでコメント化されていると、探している情報をすばやく見つけることができます。したがって、私にとっては、コメントはヘッダーファイルに配置する必要があります。

c ++では、実装をヘッダーモジュールと.cppモジュールに分割できる場合があります。ここでは、すべてのパブリック関数とメソッドが保証されている唯一の場所であるため、ドキュメントをヘッダーファイルに入れる方がきれいに見えます。