CでDoxygenを使用して、関数プロトタイプまたは定義についてコメントしますか？または両方？
いくつかのCソースが埋め込まれたDoxygenを使用しています。 .c/.hファイルのペアが与えられた場合、関数プロトタイプ（.hファイル）または関数定義（.cファイル）にDoxygenコメントを付けますか、それとも両方の場所に複製しますか？
ある場所で文書化したが、他の場所では文書化しないときに、Doxygenがコメントの欠落について警告するという問題があります。これは予想されることですか、それとも私のDoxygenは台無しになっていますか？
パブリックAPIの場合、宣言で文書化します。これは、doxygen出力を使用しない場合、ユーザーが通常最初に確認する場所であるためです。
1つの場所だけでドキュメントを作成することに問題はありませんでしたが、C++で使用しました。私はそれを疑っていますが、Cとは異なる可能性があります。
[編集]二度と書かないでください。決して。特にそのようなコピーアンドペーストの倒錯に関して、ソース内のドキュメントもDRYに従います。[/ edit]
ただし、必要かどうかを指定できます 文書化されていない要素に対する警告 。そのような警告は理論的には素晴らしいように見えますが、私の経験では、それらはすぐに助けよりも負担になります。通常、すべての機能を文書化することは道のりではありません（冗長な文書化、または文書化の妨げになること、特に文書化が多すぎることもあります）。優れたドキュメントには、それに時間を費やす知識のある人が必要です。それを考えると、それらの警告は不要です。
そして、あなたが良いドキュメントを書くためのリソース（お金、時間、何でも...）を持っていないなら、それらの警告も助けにはなりません。
この質問に対する私の答えから引用： C/C++ヘッダーファイルのドキュメント ：
インターフェイスのドキュメント（パラメーター、戻り値、what関数の機能）をインターフェイスファイル（.h）に入れ、実装のドキュメントを作成します（how関数が行う）実装ファイル（.c、.cpp、.m）。宣言の直前にクラスの概要を書いているので、読者はすぐに基本的な情報を得ることができます。
Doxygenの場合、これは、概要、パラメーター、および戻り値を説明するドキュメント（\brief、\param、\return）は、関数プロトタイプとインラインドキュメントのドキュメント化に使用されます（\details）は関数本体を文書化するために使用されます（その質問に対する私の回答も参照できます： doxygenの関数内からコメントを抽出できるようにする方法は？ ）
私はよく組み込みシステムをターゲットにしたCでDoxygenを使用します。重複willは後で混乱を招くため、私は単一のオブジェクトのドキュメントを1か所だけに書き込もうとしています。 Doxygenはドキュメントのマージをある程度行うため、原則として、パブリックAPIを.hファイルに文書化し、実際にどのように機能するかについてのメモを.cファイルに振りかけることができます。私はそれを自分でやらないようにした。
ドキュメントをある場所から別の場所に移動すると、生成される警告の量が変わる場合、それは宣言と定義の間に微妙に異なる何かがあるかもしれないというヒントかもしれません。たとえば、コードは-Wall -Wextraでクリーンにコンパイルされますか？ある場所ではコードを変更し、他の場所では変更しないマクロはありますか？もちろん、Doxygenのパーサーは完全な言語のパーサーではなく、混乱する可能性もあります。
関数定義のみをコメントしますが、C++で使用します。
両方の場所に書くのは時間を無駄にします。警告について、ドキュメントが良さそうな場合は、そのような警告を無視するのが良い方法かもしれません。
私は自分自身に同じ質問をしましたが、生成されたhtmlドキュメントを参照するときに、Doxygenが実際に対応する.hファイルの.cファイルにあるのと同じインラインドキュメントを含んでいるのを見て嬉しく驚きました。したがって、インラインドキュメントを繰り返す必要はなく、Doxygenは両方の場所に含めるのに十分賢いです！
私はバージョンDoxygenバージョン1.8.10を実行しています。