为 Javadoc 适当地记录 Varargs答案

【问题标题】：Documenting Varargs Appropriately for Javadoc为 Javadoc 适当地记录 Varargs
【发布时间】：2012-09-10 02:11:43
【问题描述】：

我在可选参数的方法中使用varargs。关于如何最好地记录该方法的任何建议？

这是一个非常人为的例子：

/**
*
* @param consumption
*     liters of liquid consumed after last pee
* @param options
*   urgency
*       how badly you have to pee on a scale of 1-3,
*       3 being the highest (default 1)
*   bribe
*       what's a toilet worth to you? (default 0)
* @return waitTime
*    minutes until you'll be able to relieve yourself
*/
public integer whenCanIUseTheBathroom(int consumption, int... options){
    // Segment handling options, defining defaults/fallbacks
    int urgency = 1;
    int bribe = 0;
    if(options.length > 0) {
        urgency = options[0];
    }
    if(options.length == 2) {
        bribe = options[1];
    }

    // Segment determining one's fate
    ...
}

【问题讨论】：

如果我理解您的 javadoc 试图告诉我的内容，我可能会找到一种更清晰的编写方式……也许您应该给出一个用法示例或定义什么是“子参数”？
抱歉，“subparam”是对options 参数提供的选项的模糊/复杂引用。我只是提高了示例代码的清晰度。
你可能最好有明确的重载——可能重定向到一个接受所有选项的统一方法，默认与否。
这不是一个很好的例子。 'options' 参数作为位掩码会更好，EnumSet, 等。通常 varargs 参数只是你可以拥有任意数量的 而无需单独描述它们的东西。

标签： java parameters documentation javadoc optional-parameters

【解决方案1】：

Varargs 通常不用于实现具有不同含义的可选参数，因为它不支持“子参数”的不同类型，提供较差的重构支持（想要插入新的“子参数”或删除旧的？），以及不灵活（你不能在提供“贿赂”时省略“紧急”）。因此，也没有使用 javadoc 记录它们的标准方法。

可选参数通常使用重载（通常使用委托）或构建器模式的变体来实现，它允许您编写：

new BathroomRequest(3).withBribe(2).compute();

有关该方法的更全面讨论，请参阅Joshua Bloch's Effective Java, item 2。

【讨论】：