6

私は C++ スタティック ライブラリを作成しており、実装ファイルに doxygen コメントを付けています。私はドキュメンテーションについてあまり気にする必要はありませんでしたが、現在、ユーザーのために適切にドキュメンテーションする必要があることに取り組んでいます。また、コーディングだけを行い、ドキュメンテーションを行いたくないという以前の悪い習慣を、より優れたソフトウェア エンジニアリングに置き換えようとしています。慣行。

とにかく、先日、ライブラリのユーザー向けのタイプ (doxygen マニュアル) と、実装の詳細を扱う将来のメンテナー向けのコメントの 2 つの異なるタイプのドキュメントが必要であることに気付きました。

私の解決策の 1 つは、ファイル、クラス、およびメソッドの doxygen コメントを実装ファイルの最後に置くことです。そこでは邪魔にならず、メソッド定義の中や周りに通常のコメントを含めて、プログラマーに利益をもたらすことができます。手間がかかることは承知していますが、2 つの別々のタイプのコメント/ドキュメントを実現するための最良の方法のように思えます。同意しますか、または役立つ可能性のある解決策/原則がありますか. サイトを見回しましたが、これを扱ったスレッドを実際に見つけることができませんでした。

また、インターフェイス ファイルにコメントを散らかしたくはありません。インターフェイス自体に語らせたほうがよいと思うからです。ユーザーがライブラリ インターフェイスをより深く理解する必要がある場合に、マニュアルを参照できるようにしたいと考えています。私はここで正しい軌道に乗っていますか？

ご意見やご感想をお待ちしております。

編集：コメントをありがとうございます。私はそれらを聞いて多くのことを学びました。メンテナーにとって役立つコード コメントからユーザー マニュアルを分離する方法について、理解が深まったと思います。ライブラリの使用方法を説明するのに役立つ「散文」スタイルのマニュアルを作成するという @jalf のアイデアが気に入っています。これは単なるリファレンスマニュアルよりも優れていると本当に思います。とは言っても……リファレンスマニュアルもかなり重宝しそうな気がします。彼のアドバイスを他の人の考えと組み合わせて、ハイブリッドを作成しようと思います.コードにマニュアル全体が差し込まれていないという考えでした。これを回避するには、doxygen のすべてのコメントを実装ファイルの末尾に配置します。これにより、ヘッダーがきれいになり、実装がきれいになり、実装を維持している人にとって有用なコメントが配置されます。これが実際に機能するかどうかを確認します。これらは、これまでに学んだことに対する私の考えです。私のアプローチがうまくいくか、実用的であるかについては確信が持てません。時間だけが教えてくれます。

4

6 に答える 6

6

最良の方法は、ヘッダー ファイルに Doxygen を使用して各クラス/メソッドの使用方法を (ユーザーに) 説明し、.cpp ファイル内でコメントを使用して実装の詳細を説明することだと思います。

于 2010-01-19T02:18:58.577 に答える
6

私は一般的に、doxygen コメントなどのように、ユーザーへのコメントをコード内でインライン化するべきではないと考えています。散文形式の別のドキュメントにする必要があります。ライブラリのユーザーとして、関数の各パラメーターが何を意味するかを知る必要はありません。うまくいけば、それは明らかです。関数が何をするのかを知る必要があります。そして、なぜそれを行うのか、いつ呼び出すのかを知る必要があります。そして、どの事前条件と事後条件が適用されるかを知る必要があります。関数を呼び出すときに関数はどのような仮定を行い、関数が戻るときにどのような保証を提供しますか?

ライブラリのユーザーにはコメントは必要ありません。ドキュメントが必要です。ライブラリがどのように構造化され、どのように機能し、どのように使用するかを説明し、コードの外で実際のテキスト ドキュメントで説明します。

もちろん、コードにはメンテナー向けのコメントが含まれている場合があり、実装がそのように見える理由や、明らかでない場合はどのように機能するかを説明しています。ただし、ライブラリのユーザーが必要とするドキュメントは、コードに含めるべきではありません。

于 2010-01-19T03:10:56.897 に答える
4

よくできました。Doxygen のコメントは、コードを読むときと、生成された HTML を読むときの両方で非常に便利です。すべての難しさはWell doneにあります。

私のアプローチは次のとおりです。

  • ライブラリのユーザー向けに、ヘッダー ファイルに Doxygen のコメントを入れて、その関数の目的と、すべての引数、戻り値、考えられる副作用を詳述することでその使用方法を説明しています。生成されたドキュメントがリファレンス マニュアルになるようにフォーマットするようにしています。

  • メンテナーのために、自己コメントのコードでは不十分な場合はいつでも、基本的な (Doxygen ではない) コメントを実装ファイルに入れます。

さらに、リファレンス マニュアルの詳細を示すユーザー ガイドの形で、libray の新しいユーザーにライブラリのさまざまな機能の使用方法を説明するために、特別な紹介ファイル (コードは別として) を Doxygen 形式で作成します。このイントロは、Doxygen によって生成されたドキュメントのフロント ページとして表示されます。

于 2010-01-19T12:45:25.127 に答える
3

Doxygen では、 \internalコマンドとINTERNAL_DOCSオプションを使用して、2 つのバージョンのドキュメント (ユーザー用と「内部使用」用) を作成できます。条件付きセクションを使用して、よりきめ細かい制御を行うこともできます ( \ifコマンドとENABLED_SECTIONSオプションを参照してください)。

他の人がすでに指摘しているように、ユーザー (および場合によってはメンテナー) に、厳密なコード コメントよりも高いレベルで何かを提供することも役立ちます。\mainpage、 \page、[sub[sub]]section および \par コマンドを使用して、Doxygen を使用することもできます。

于 2010-01-19T14:04:51.650 に答える
1

簡単な答えはありません。優れたドキュメントは難しいです。

個人的にはレイヤードモデルが一番いいと思います。

  • 散文の高レベルのドキュメント。写真やビデオは非常に適切です。
  • 参照レベルのドキュメントはDoxygenである必要があります（手元にあるコメントだけでなく、よくできたdoxygen）。
  • メンテナドキュメントはリファレンスドキュメントに表示されるべきではありませんが、Éricが指摘しているようにdoxygenである可能性があります。

私はRakNetで使用されているドキュメントスタイルが本当に好きです。著者は広範なDoxygenコメントを使用し、生成されたリファレンスマニュアルを提供します。彼はまた、いくつかのプレーンなhtmlチュートリアルを提供しています。何よりも、彼はいくつかのより複雑な機能のビデオウォークスルーを提供しています。

もう1つの良い例はSFMLです。品質はRakNetほど良くはありませんが、それでも非常に良いです。彼は、 doxygenで生成されたドキュメントの概要ページを提供しています。いくつかのプレーンなhtmlチュートリアルとプレーンなhtml機能/概要ページがあります。

Doxygenで生成されたドキュメントは、始めたばかりのときは一般的に低レベルであるため、これらのスタイルを好みますが、溝に入ったら完全に簡潔になります。

于 2010-02-10T17:08:20.697 に答える
1

この論文をご覧になることをお勧めします: http://www.literateprogramming.com/knuthweb.pdf

私は通常、これらのアイデアを自分のプロジェクトに適用しました (Doxygen を使用)。また、IDE を離れる必要がないため、ドキュメントを最新の状態に保つのにも役立ちます。そのため、コーディング中に注釈を付けたり、後で最終的な PDF ドキュメントを修正して、更新または詳細が必要なものを確認したりできます。

私の経験では、Doxygen では、pdf の見栄えを良くしたり、グラフや写真を適切に配置したりするなどの作業が必要ですが、方法を見つけてツールの制限を理解すれば、作業は非常にうまくいきます。

私の提案は、Kyle Lutz と Eric Malefant が既に述べたことに加えて、関連するクラスについての長い説明を独自のファイルに入れ (私はそのためにヘッダー ファイルを使用します)、Doxygen タグを使用して他の部分への参照を追加することです。これらのヘッダーを Doxygen 構成ファイルに含める必要があるだけです (パターン マッチングを使用)。これにより、ヘッダーが煩雑になるのを回避できます。

于 2010-01-19T21:08:29.897 に答える