java - 为 Javadoc 适当记录 Varargs

Question

我在可选参数的方法中使用 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
    ...
}

Answer 1

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

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

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

有关该方法的更详尽讨论，请参阅 Joshua Bloch's Effective Java, item 2 .