3

related to Using Doxygen with C, do you comment the function prototype or the definition? Or both? .

I think the right way is to doxygen the .h function prototype, with \param, \return, and \brief , because this hides the implementation and exposes only the API to functions that include my .h file; and to doxygen the .c function implementation, with more \details. So far so good. this also is the advice on stackoverflow.

Is it possible to tell doxygen to combine the .c and .h documentation? because the .c implementation can be a prototype, I don't even need the .h function prototype, but I would need doxygen to pull the .h doxygen \param, \return, and \brief over to the .c implementation documentation in html and latex. right now, having the functions twice in different places is confusing and painful. at the very least, I would want the \param, \return, and \brief to reappear with the function implementation.

/iaw

Community
  • 1
  • 1
ivo Welch
  • 2,427
  • 2
  • 23
  • 31

1 Answers1

1

If this was your header:

/**
 * @brief Main function
 * 
 * @param argc number of arguments
 * @param argv array of arguments
 * 
 * @return 0
 */
int main(int argc, char* argv[]);

And this your source:

/**
 * @internal
 *
 * This is an internal implementation command.
 * 
 * @endinternal
 */
int main(int argc, char* argv[])
{
    return 0;
}

Your comments will be merged in the documentation. In this example, INTERNAL_DOCS has to be enabled in your configuration to have the implementation comment. You will find the merged documentation at the page of the header file. The page of the source file will only show the implementation command.

Jonas Wolf
  • 1,154
  • 1
  • 12
  • 20
  • is it possible to merge the code, too? that is, so that my doxygen output just shows one set of output, first the brief (from .h) then params (.h) then return (.h) then implementation comment (.c) then source (.c)? the quasi-mandatory separation into .h and .c files (and single-pass nature requiring forward declarations) was useful in 1978, but its requirement today is just self-inflicted pain. – ivo Welch Jun 16 '14 at 04:11
  • @ivoWelch I am not sure if I got you right. The code (source and header) structue is okay. You just want one ouptut file for both header and source? – Jonas Wolf Jun 16 '14 at 04:47
  • When you say,"merge the code too", do you mean inline documents in the source code (e.g. ///inline comment in the code)? That stuff will get appended to the end of the documentation block in the output. – Nick Jun 18 '14 at 15:23