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

possible duplicate of [Issue getting Doxygen to document an enum in C](http://stackoverflow.com/questions/1717941/issue-getting-doxygen-to-document-an-enum-in-c) — Chris, Aug 20 '12 at 16:41

score 31 · Accepted Answer · edited Jul 04 '23 at 12:26

31

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.

edited Jul 04 '23 at 12:26

S. Kalabukha

58
8

answered Aug 20 '12 at 16:41

Chris

44,602
16
137
156

Ok so I added one of those you listed above but it is still not showing the description of my main() as I had given in the example above... it just documents the constants and the struct (like before) but still nothing from inside my main(). – user1496542 Aug 20 '12 at 17:04
Well you mention constants and structs but there are none in your example. Generally it is the lack of documentation for the file which is why functions do not appear in the documentation. If this is not fixing the problem then I don't know what to suggest without seeing the rest of your code. Please post a [minimal, self-contained example](http://sscce.org/) which reproduces the problem you are having. – Chris Aug 20 '12 at 17:49
ok I just updated. The stuff that worked I didn't think I needed to include so my apologies. But I tried the suggestions given in an answer below as well but still no luck :/ – user1496542 Aug 20 '12 at 18:02
I still get the expected out (function `main` documented) when I run doxygen on your example code. Try using the default doxygen configuration file. If that fixes the problem then try and compare the configuration file you are using with the default and see where the two differ. If that doesn't solve the problem then we are missing some information. – Chris Aug 20 '12 at 19:57

score 4 · Answer 2 · answered Aug 20 '12 at 17:19

4

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

answered Aug 20 '12 at 17:19

doxygen

14,341
2
43
37

I tried what you suggested and it still no main function documentation :( – user1496542 Aug 20 '12 at 17:43
1

Which version of doxygen did your use? (I got this working fine with 1.8.2) – doxygen Aug 20 '12 at 20:00

score 2 · Answer 3 · answered Aug 03 '13 at 08:47

2

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.

answered Aug 03 '13 at 08:47

Someone13

443
1
6
18

Thanks a lot. Despite all tech advancements it's almost impossible to find right answer. this should get +1000000 – Kovalex Nov 20 '19 at 16:23

score 0 · Answer 4 · edited Jan 13 '19 at 14:24

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?

Doxygen not documenting main function in main.cpp

4 Answers4

Linked