web-dev-qa-db-ja.com

HまたはCPPファイルで、内部ライブラリのdoxygenコメントブロックを配置する場所は？

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

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

長所：

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

短所：

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

だから、あなたはどう思いますか、おそらく示唆していますか？

documentationcommentsdoxygen
91
Singulus

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

クラスコメントはクラスの前に、メソッドコメントはメソッドの前に配置します。

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

72
Andy Dent

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

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

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

例えば：

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;
}
65
Daniel Buckmaster

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

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

17
ErikJ

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

ソース：これで、コメントを見ながら実際の関数を読むことができます。

ヘッダーでコメント化されたすべてのグローバル関数と、ソースでコメント化されたローカル関数を使用します。必要に応じて、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か所で作成すると同時に、コードファイルのノイズが少なくなります。

11
eaanon01

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

すべてを文書化しますが、一般的にはパブリックインターフェイスのみを抽出します。

2
graham.reeds

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

2
mouviciel

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

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

1
Sinclair