Doxygen not documenting main function in main.cpp

Question

I have a main.cpp that contains a struct, some global constants and a main function.

I ran doxygen and the only documentation I am getting in the output index.html is for my struct.

I want doxygen to document into that index.html file my main() as well. What am I doing incorrectly?

    /// 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;
    }

Answer 1

This is because you are documenting a global object which doxygen, by default, does not document. From the doxygen manual (emphasis mine):

To document a member of a C++ class, you must also document the class itself. The same holds for namespaces. To document a global C function, typedef, enum or preprocessor definition you must first document the file that contains it (usually this will be a header file, because that file contains the information that is exported to other source files).

Let's repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined. In other words, there must at least be a

 /*! \\file */ 

or a

 /** @file */ 

line in this file.

So try adding one of the above two lines to your main.cpp file.

Answer 2

Make sure HIDE_IN_BODY_DOCS is set to NO and use something like this:

/// \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;
}

Answer 3

For me, I had to make sure I had this set:

SHOW_FILES = YES

All your global functions will appears in the Files tab inside of each file. Also, it helps if you have @file or \\file defined at the top of your code.

Answer 4

From the online manual in the "Documentation at other places" section: http://www.doxygen.nl/manual/docblocks.html#specialblock

"Doxygen allows you to put your documentation blocks practically anywhere ( the exception is inside the body of a function or inside a normal C style comment block)."

This makes some sense because the nitty gritty of HOW a function works (its implementation) is usually not desired. I believe the purpose of doxygen is to assist in documentation that is easily searchable to allow coders to find where things are and look up what they do (and what parameters are passed into it, what it returns, etc) to learn how to use them, but not how its actually implemented. That would require actually looking at the function source (which is also available in the doxygen generated files). Also, if you'll notice, all the examples (i think) show documentation in header files, which lack any implementation which leads me to believe that documentation is intended for the header files, but the tool gives you the flexibility to put is in source files as well.

That's my view anyway. Anyone think differently?