doxygen - ライブラリの文書化-パブリックヘッダーのすべてまたは関数のみ？

Question

ライブラリを開発して文書化する場合..すべてのソースファイルからのすべての関数/データ構造を文書化しますか、それともパブリックヘッダーに表示されるパブリックのものだけを文書化しますか？

私は2番目のオプションに傾いています、これは大丈夫ですか？

Answer 1

それは、たとえば5年後に、そのライブラリの何かを変更したいかどうかによって異なります。その場合、ドキュメントを用意しておくと便利です。ただし、「プライベート」ドキュメントをユーザーに提供するドキュメントから何らかの方法で分離する必要があります。これは、入力が異なる2つの別々のdoxygen構成ファイルを使用して実行できます。

Answer 2

あなたの質問に対する答えは、誰がドキュメントを読むかによって異なります。ドキュメントがAPIのユーザーに提供される場合は、パブリックインターフェイスのドキュメントのみをユーザーに提供する方がよいでしょう。このように、彼らは彼らに関係のない詳細に圧倒されることはありません。

一方、ライブラリを管理している人がドキュメントを読む場合は、パブリックコードとプライベートコードの両方に関するドキュメントを含める必要があります。

現在、私はarneに対して少し異なるアプローチを使用しています。パブリックインターフェイスに必要なヘッダーファイルをパッケージ化するために別のディレクトリにコピーするスクリプトがあります。これはとにかくリリースを作成するために必要です。スクリプトはまた、Doxyfile構成をそのディレクトリにコピーしてから、縮小されたファイルのセットに対してdoxygenを実行します。そうすれば、パブリックドキュメントとプライベートドキュメントの両方を作成するために使用する1つのdoxygen構成ファイルがあります。