Writing Javadoc for functions with (simulated) optional/default arguments

user_1908650 0
Viewed 2105

I have Java wrappers for some C++ code in which I am simulating default arguments by manually overloading the relevant method(s). [Example is as in Does Java support default parameter values? .] In one case the C++ fn has 3 optional arguments, so I have had to write 8 methods in Java.

Now I want to write JavaDocs for said method. Is there any way to avoid writing essentially the same text 8 times? As well as being verbose, that would be a maintenance nightmare...

EDit: here is a toy example illustrating the signatures for the methods:

void foo(int i, String s, double d);
void foo(int i, String s);
void foo(int i, double d);
void foo(int i);
void foo(String s, double d);
void foo(String s);
void foo(double d);
void foo();
javadoc default-value optional-parameters java
1 Answers

One solution is to write the full Javadoc documentation in the method that has all parameters, then link to that documentation in the overloads, using the @link and/or @see directives, for example:

/**
 * The parameters in the wrapped C++ method are all  optional,
 * so we had to write an overload for each parameter combination.
 * @param i the int parameter used for x. 
 * @param s the string parameter used for y.
 * @param d the double parameter used for z.
 */
void foo(int i, String s, double d);

/**
 * Overload of the {@link #foo(int, String, double)} method with a default {@code d}.
 */
void foo(int i, String s);

/**
 * @see #foo(int, String, double)
 */
void foo(int i, double d);

...
user_5249000
Related