☰

doxygen を使用してコードを文書化するための最良のヒントは何ですか? [closed] 質問する

tag-icon • tag-icon c++ c documentation doxygen
doxygen を使用してコードを文書化するための最良のヒントは何ですか? [closed] 質問する

私のチームは、特にパブリック API ヘッダーに注意しながら、doxygen を使用して C コードのドキュメント化を開始しています。doxygen には柔軟性が高く、さまざまな特殊コマンドが用意されているようですが、これは素晴らしいことですが、試行錯誤しないと、何が良くて何が悪いのかはわかりません。

コードをマークアップするときによく使う方法は何ですか? 必ずすべきことと、してはいけないことは何ですか?
投票しやすいように、回答ごとに 1 つずつ、おすすめのヒントを教えてください。

私は、チームの残りのメンバーが開始できるようにテンプレートを提供することを含め、API ドキュメントへの全体的なアプローチを定義しようとしています。これまでのところ、次のようなものがあります。

/**
 * @file   example_action.h
 * @Author Me ([email protected])
 * @date   September, 2008
 * @brief  Brief description of file.
 *
 * Detailed description of file.
 */

/**
 * @name    Example API Actions
 * @brief   Example actions available.
 * @ingroup example
 *
 * This API provides certain actions as an example.
 *
 * @param [in] repeat  Number of times to do nothing.
 *
 * @retval TRUE   Successfully did nothing.
 * @retval FALSE  Oops, did something.
 *
 * Example Usage:
 * @code
 *    example_nada(3); // Do nothing 3 times.
 * @endcode
 */
boolean example(int repeat);

ベストアンサー1

ディレクティブにファイル名を書く必要はなく、書くべきでもありません。doxygen は@fileファイル名を自動的に読み取ります。ファイル名を書く場合の問題は、ファイルの名前を変更するとディレクティブも変更しなければならないことです@file。

ソース コントロール システムでは、誰かが手動でファイルを編集するよりもはるかに優れた処理が実行されるため、情報の提供@authorも@dateほとんどの場合役に立ちません。

@briefまた、次の Doxygen 構文を使用し、doxygen の設定で JAVADOC_AUTOBRIEF を有効にすると、記述する必要もありません。

/*! Short Description on the first line

    Detailed description...
    ...
*/
void foo(void) {}

関数のディレクティブ@nameも、ほとんどの場合 100% 冗長であり、まったく役に立ちません。関数の名前を変更した場合にのみエラーが発生し、 doxygen は変更されません@name。

おすすめ記事