4

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();
Mohan
  • 7,302
  • 5
  • 32
  • 55
  • Could you please give us details about that method? Maybe some code? – Seelenvirtuose Nov 18 '17 at 13:33
  • I ask, because there seems to be no easy way for your requirement. But there might be good workarounds. – Seelenvirtuose Nov 18 '17 at 13:46
  • @Seelenvirtuose: see above. (The real example has a lot of clutter irrelevant to the q., so I have substituted a smaller one.) – Mohan Nov 19 '17 at 07:52
  • I would replace all those methods with a [message object](https://refactoring.com/catalog/replaceMethodWithMethodObject.html) that has all those parameters as fields. You then can use a _builder_ for such an object. The documentation then changes a bit, because you now document a class and a builder instead of methods. Usage also changes, of course. Would that be acceptable? – Seelenvirtuose Nov 19 '17 at 11:53
  • Another approach is a simple parameter object. Then you only have one method to document. – Seelenvirtuose Nov 19 '17 at 17:48
  • @Seelenvirtuose Not really. It simplifies the creation of the documentation at the cost of complicating the interface for the user (and making it diverge from the code being wrapped), which is the cart leading the horse. Thanks for the thoughts, though. What I was hoping for was a Javadoc directive letting you copy chunks of Javadoc from one place to another. IIRC doxygen allows this. See https://stackoverflow.com/questions/5002827/doxygen-copydoc-tag-to-reuse-code-examples – Mohan Nov 20 '17 at 04:15

1 Answers1

6

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);

...
Lolo
  • 4,277
  • 2
  • 25
  • 24