web-dev-qa-db-ja.com

Doxygenがmain.cppの主な機能を文書化していない

構造体、いくつかのグローバル定数、およびメイン関数を含むmain.cppがあります。

私はdoxygenを実行しましたが、出力index.htmlで取得している唯一のドキュメントは構造体用です。

私はdoxygenが私のmain（）もそのindex.htmlファイルに文書化することを望みます。私は間違って何をしていますか？

    /// Definition of Pi
    const auto Pi = 3.141592653589793238462643383279502884197169399;

    /// \struct myStruc
    /// \brief myStruc description
    ///
    struct myStruc
    {
         /// Comments inside myStruc
    };

    /// \file

    /// \brief  Main function
    /// \param  argc An integer argument count of the command line arguments
    /// \param  argv An argument vector of the command line arguments
    /// \return an integer 0 upon exit success
    int main(int argc, char** argv)
    {
        /// Comments I would like to be documented in as well
        return 0;
    }
c++doxygenmain
18
user1496542

これは、doxygenがデフォルトで文書化しないグローバルオブジェクトを文書化しているためです。 doxygen manual （私の強調）から：

C++クラスのメンバーを文書化するには、クラス自体も文書化する必要があります。名前空間についても同じことが言えます。 グローバルC関数、typedef、列挙型、またはプリプロセッサ定義を文書化するには、最初にそれを含むファイルを文書化する必要があります（通常、これはヘッダーファイルになります。そのファイルには、他のソースファイルにエクスポートされる情報が含まれています）。

繰り返しますが、見落とされがちです：グローバルオブジェクト（関数、typedef、列挙型、マクロなど）を文書化するには、それらが定義されているファイルを文書化する必要があります。言い換えると、少なくとも

/*! \file */

または

/** @file */

このファイルの行。

したがって、上記の2行のいずれかをmain.cppファイルに追加してみてください。

24
Chris

確認してください HIDE_IN_BODY_DOCSはNOに設定され、次のようなものを使用します。

/// \file

/// \brief  Main function
/// \param  argc An integer argument count of the command line arguments
/// \param  argv An argument vector of the command line arguments
/// \return an integer 0 upon exit success
int main(int argc, char** argv)
{
  /// Comments I would like to be documented in as well
  return 0;
}
3
doxygen

私にとって、私はこのセットを持っていることを確認する必要がありました：

SHOW_FILES = YES

すべてのグローバル関数は、各ファイル内の[ファイル]タブに表示されます。また、コードの先頭に@fileまたは\ fileを定義している場合にも役立ちます。

1
Someone13

「他の場所でのドキュメント」セクションのオンラインマニュアルから： http://www.doxygen.nl/manual/docblocks.html#specialblock

「Doxygenを使用すると、ドキュメントブロックを事実上どこにでも配置できます（例外は関数の本体内または通常のCスタイルのコメントブロック内にあります）。」

関数がどのように機能するか（その実装）の本質は通常望ましくないため、これはある程度意味があります。 doxygenの目的は、簡単に検索できるドキュメントを支援して、コーダーが物事の場所を見つけ、それらが何をするのか（そして、どのパラメーターがそれに渡され、何が返されるのかなど）を調べて、それらの使用方法を学ぶことができるようにすることだと思います。 、しかし実際にどのように実装されたかではありません。それには、実際に関数ソースを調べる必要があります（これは、doxygenで生成されたファイルでも利用できます）。また、お気づきの方もいらっしゃると思いますが、すべての例（私は思う）はヘッダーファイルのドキュメントを示していますが、ドキュメントはヘッダーファイルを対象としていると私は信じる実装がありませんが、ツールを使用すると柔軟性が得られます。ソースファイルも同様です。

それはとにかく私の見解です。誰か違う考えですか？

0
radensb