26

私は Doxygen を組み込みの C ソースと共に使用しています。.c/.h ファイルのペアが与えられた場合、Doxygen コメントを関数プロトタイプ (.h ファイル) または関数定義 (.c ファイル) に配置しますか? それとも両方に複製しますか?

ある場所でドキュメントを作成し、他の場所ではドキュメントを作成しないと、Doxygen がコメントの欠落について警告するという問題が発生しています。これは予想どおりですか、それとも私のDoxygenが台無しですか?

4

5 に答える 5

20

パブリック API については、宣言で文書化します。doxygen の出力を使用しない場合、ユーザーが通常最初に確認する場所だからです。

1 か所だけを文書化しても問題はありませんでしたが、C++ で使用しました。私はそれを疑いますが、Cとは違うかもしれません。

[編集] 二度と書かないでください。一度もない。ソース内のドキュメントも、特にそのようなコピー アンド ペーストの倒錯に関して、DRY に従います。[/編集]

ただし、文書化されていない要素について警告するかどうかを指定できます。このような警告は理論上は良さそうに見えますが、私の経験では、すぐに役立つというよりもむしろ負担になります。通常、すべての関数を文書化することは適切ではありません (文書化が冗長になったり、文書化の妨げになったり、特に文書化が多すぎたりすることがあります)。優れたドキュメンテーションには、それに時間を費やす知識のある人が必要です。それを考えると、これらの警告は不要です。

また、優れたドキュメントを作成するためのリソース (お金、時間など...) がない場合は、これらの警告も役に立ちません。

于 2009-08-13T13:49:26.087 に答える
10

この質問に対する私の回答から引用: C/C++ Header file documentation :

インターフェイスのドキュメント (パラメーター、戻り値、関数の動作) をインターフェイス ファイル ( .h ) に、実装のドキュメント (関数の動作方法) を実装ファイル (.c、.cpp、.メートル）。宣言の直前にクラスの概要を書くので、読者はすぐに基本的な情報を知ることができます。

Doxygen では、これは、概要、パラメーター、および戻り値を説明するドキュメント ( \brief、\param、\return) が関数プロトタイプのドキュメント化に使用され、インライン ドキュメント ( \details) が関数本体のドキュメント化に使用されることを意味します (その質問に対する私の回答を参照することもできます: How to be doxygen の関数内からコメントを抽出できますか? )

于 2009-08-26T08:20:57.380 に答える
4

私は、組み込みシステムをターゲットとする C で Doxygen をよく使用します。重複すると後で混乱が生じるため、単一のオブジェクトのドキュメントを 1 か所だけに書くようにしています。Doxygen はドキュメントのマージをある程度行うため、原則として、パブリック API を.hファイルにドキュメント化し、実際にどのように動作するかについていくつかのメモを.cファイルに散りばめることができます。私自身はそうしないように努めてきました。

ドキュメントをある場所から別の場所に移動すると、生成される警告の量が変化する場合、それは宣言と定義の間に微妙な違いがある可能性があることを示唆している可能性があります。たとえば、コードは -Wall -Wextra でクリーンにコンパイルされますか? ある場所でコードを変更し、他の場所では変更しないマクロはありますか? もちろん、Doxygen のパーサーは完全な言語パーサーではなく、混乱させる可能性もあります。

于 2009-08-13T17:42:35.720 に答える
0

私は自分自身に同じ質問をしましたが、生成された html ドキュメントをブラウズすると、Doxygen が対応する .h ファイルの .c ファイルにあるものと同じインライン ドキュメントを実際に含んでいることに驚きました。したがって、インライン ドキュメントを繰り返す必要はありません。

バージョン Doxygen バージョン 1.8.10 を実行しています。

于 2015-08-26T02:24:15.297 に答える