21

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;
    }
Improve this question
1

4 Answers 4

Reset to default
33

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.

Improve this answer
Sign up to request clarification or add additional context in comments.

4 Comments

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().
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 which reproduces the problem you are having.
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 :/
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.
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;
}
Improve this answer

2 Comments

I tried what you suggested and it still no main function documentation :(
Which version of doxygen did your use? (I got this working fine with 1.8.2)
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.

Improve this answer

1 Comment

Thanks a lot. Despite all tech advancements it's almost impossible to find right answer. this should get +1000000
0

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?

Improve this answer

Comments

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.