I am surprised that Doxygen seems unable to inherit function arguments from another documented function. Say I've already documented f
:
/**
* Add them
*
* Add them
*
* @param a An integer.
*
* @param b An integer.
*
* @param c An integer.
*
* @return Return the sum.
*
*/
int f(int a, int b, int c) { return a + b + c; }
Now I want to document another function with the same a
and b
from f
. Using roxygen2
for documenting C++ function exposed through Rcpp
module, I can write the following:
/**
* Do something
*
* Do something
*
* @inheritParams f
*
* @param d A double
*
* @return Return the result.
*
*/
double g(int a, int b, double d} { return (a + b) * d; }
The above code will inherit the description of a
and b
from f
.
I have so many functions whose arguments are more or less the same. Copying and pasting the parameter description is quite daunting. How to achieve function parameter inheritance in Doxygen in 2024?
Thank you!
The @copydoc
has as disadvantage that it will copy not only all parameters, resulting in a warning for parameter c
, but also the brief and detailed description etc. (see the function g
below)
Doxygen is lacking, at the moment, a @copyparam
command, but with the \snippet{doc}
command there are some possibilities as shown in the example below (result in function g1
).
[f_p]
parts in the function f
. We also use the \noop
command here so the [f_p]
won't show up in the documentation of f
*
as otherwise these would appear in the resulting output of g1
as list markers.g1
we need the reference: @snippet{doc} aa.h f_p
so the snippet is included as documentation (my file is aa.h
hence the name in the command).It all has been tested with the current doxygen version 1.10.0 (due to a problem in doxygen 1.10.0 the construct @snippet{doc} this f_p
is not possible and hence the explicit file name in @snippet{doc} aa.h f_p
)
/// \file
/**
* Add them
*
* Add them
* \noop [f_p]
@param a An integer.
@param b An integer.
\noop [f_p]
*
* @param c An integer.
*
* @return Return the sum.
*
*/
int f(int a, int b, int c) { return a + b + c; }
/**
* Do something
*
* Do something
*
* @copydoc f
*
* @param d A double
*
* @return Return the result.
*
*/
double g(int a, int b, double d) { return (a + b) * d; }
/**
* Do something
*
* Do something
*
* @snippet{doc} aa.h f_p
* @param d A double
*
* @return Return the result.
*
*/
double g1(int a, int b, double d) { return (a + b) * d; }
Result: