doxygen — combine .c and .h doc for same files?

Question

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

Jonas Wolf Jonas Wolf · Accepted Answer · 2014-06-15T06:33:45

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.

doxygen — combine .c and .h doc for same files?

1 Answers