-1

In a C++ project, I describe methods and functions in my headers like so:

int foo(float, bool, std::string);

and in my implementation, name the parameters:

int
foo(float f,
    bool b,
    std::string str)
{
    ...
}

and if I generate my documentation with Doxygen with SOURCE_BROWSER=NO, VERBATIM_HEADERS=NO and EXTRACT_ALL=YES then the resulting documentation contains the function signature with the parameter names which is what I want. But I also end up with all of my .cpp files in the 'File List' section alongside the headers.

I want to completely hide my source files but then I want to also have my documentation to contain parameter names without having to go through the project and add thousands of them to the includes myself.

I have tried adding the src/ folder to EXCLUDE which does hide the sources but then they aren't parsed at all and the opposite problem arises where the parameters are nameless again.

Is there any way I can eat my cake and have it too?

agregate
  • 163
  • 6
  • 1
    IMHO, bad coding style. I believe that header files should state how to use the functions. A person should not have to go to the source code to figure out what the calling parameters are, especially when there are multiple parameters of the same type. – Thomas Matthews Apr 03 '21 at 21:21
  • @ThomasMatthews I agree and even more so now that I'm potentially wasting time going over thousands of them to change them. At the very least I have the documented param names right above the function definitions... – agregate Apr 03 '21 at 21:23
  • Have you tried using the `/*! \brief` command along with the `\param` keyword? This will work in the source code and in the header file. Our shop's guideline is to use `\brief` in the header file and `\details` in the source code. – Thomas Matthews Apr 03 '21 at 21:24
  • @ThomasMatthews Other than the fact that I'm using the Javadoc style (`/** @brief`) I am doing exactly this. – agregate Apr 03 '21 at 21:25
  • Why the downvote? – agregate Apr 05 '21 at 17:09

1 Answers1

-1

It turns out if I disable EXTRACT_ALL=yes and add @file to the start of only the files I want to show (so all the headers) then I can retain the parameter names from sources while hiding the files.

Perhaps not the best solution given undocumented functions will no longer display but since they all are in this project it does not pose a problem.

agregate
  • 163
  • 6