为具有（模拟的）可选/默认参数的函数编写 Javadoc答案

【问题标题】：Writing Javadoc for functions with (simulated) optional/default arguments为具有（模拟的）可选/默认参数的函数编写 Javadoc
【发布时间】：2018-05-02 03:04:28
【问题描述】：

我有一些 C++ 代码的 Java 包装器，我在其中通过手动重载相关方法来模拟默认参数。 [例如Does Java support default parameter values? 中的例子。]在一种情况下，C++ fn 有 3 个可选参数，所以我不得不用 Java 编写 8 个方法。

现在我想为上述方法编写 JavaDocs。有什么方法可以避免将基本相同的文本写 8 次？除了冗长之外，这将是一场维护噩梦......

编辑：这是一个说明方法签名的玩具示例：

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

【问题讨论】：

您能否详细介绍一下该方法？也许一些代码？
我问，因为您的要求似乎没有简单的方法。但可能有很好的解决方法。
@Seelenvirtuose：见上文。（真实的例子有很多与 q 无关的杂物，所以我替换了一个较小的。）
我会用 message object 替换所有这些方法，该 message object 将所有这些参数作为字段。然后，您可以为这样的对象使用 builder。然后文档会发生一些变化，因为您现在记录了一个类和一个构建器而不是方法。当然，用法也会发生变化。这可以接受吗？
另一种方法是简单的参数对象。那么你只有一种方法可以记录。

标签： java javadoc default-value optional-parameters

【解决方案1】：

一种解决方案是在包含所有参数的方法中编写完整的 Javadoc 文档，然后使用 @link 和/或 @see 指令在重载中链接到该文档，例如：

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

...

【讨论】：