適用於Javadoc的可變參數記錄

我在可選參數的方法中使用varargs。關於如何最好地記錄該方法的任何建議？適用於Javadoc的可變參數記錄

這裏是一個奇妙的人爲的例子：

/** 
* 
* @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 
    ... 
}

來源

2012-09-10 fny

如果我明白你的javadoc試圖告訴我什麼，我可能會找到更清晰的方式來寫它...也許你應該給一個用法示例或定義什麼是「子參數」？ – meriton

道歉，「subparam」是對'options'參數提供的選項的模糊/複雜的引用。我剛剛改進了示例代碼的清晰度。 – fny

你可能最好有明確的重載 - 可能重定向到接受所有選項的統一方法，默認或不是。 –

可變參數通常不用於實現可選參數與不同的含義，因爲它不支持不同類型的「subparams」，提供了重構的支持較差（要插入一個新的「子標籤」還是刪除舊的標籤？），並且不靈活（在提供「賄賂」時不能省略「緊急性」）。因此，用javadoc也沒有標準的方法來記錄它們。

可選參數使用重載（通常與代表團）通常實現的，或者建造者模式的一個變種，它允許你寫：

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

對於方法的更深入的討論，請參閱Joshua Bloch's Effective Java, item 2。

來源

2012-09-10 05:22:05 meriton

適用於Javadoc的可變參數記錄

回答

相關問題