什麼是正確的方法把一個Javadoc的param標籤中的多行？

Question

我找不到任何有關javadoc參數中是否有多行信息的信息。我正在製作一個國際象棋引擎，我希望能夠解析一個字符串來生成一個棋盤。如下所示，可以這樣做嗎？

/** 
* Creates a board based on a string. 
* @param boardString The string to be parsed. Must be of the format: 
*  "8x8\n" + 
*  "br,bn,bb,bq,bk,bb,bn,br\n" + 
*  "bp,bp,bp,bp,bp,bp,bp,bp\n" + 
*  " , , , , , , , \n" + 
*  " , , , , , , , \n" + 
*  " , , , , , , , \n" + 
*  " , , , , , , , \n" + 
*  "wp,wp,wp,wp,wp,wp,wp,wp\n" + 
*  "wr,wn,wb,wq,wk,wb,wn,wr" 
*/ 

編輯：這已被標記爲重複。我相信這不是重複的原因是因爲另一個問題僅僅是創建多行javadoc註釋，而這個問題是關於將多行作爲參數參數的一部分。

Answer 1

我想說，你做這件事的方式沒問題（編輯：哦，也許不是。如果你想保持特定的格式，你需要一份好的<pre>。幸運的是，答案仍然有效！）。

考慮從Apache的百科全書BooleanUtils一個專家級的例子...

/** 
* <p>Converts an Integer to a boolean specifying the conversion values.</p> 
* 
* <pre> 
* BooleanUtils.toBoolean(new Integer(0), new Integer(1), new Integer(0)) = false 
* BooleanUtils.toBoolean(new Integer(1), new Integer(1), new Integer(0)) = true 
* BooleanUtils.toBoolean(new Integer(2), new Integer(1), new Integer(2)) = false 
* BooleanUtils.toBoolean(new Integer(2), new Integer(2), new Integer(0)) = true 
* BooleanUtils.toBoolean(null, null, new Integer(0))      = true 
* </pre> 
* 
* @param value the Integer to convert 
* @param trueValue the value to match for <code>true</code>, 
* may be <code>null</code> 
* @param falseValue the value to match for <code>false</code>, 
* may be <code>null</code> 
* @return <code>true</code> or <code>false</code> 
* @throws IllegalArgumentException if no match 
*/ 
public static boolean toBoolean(Integer value, Integer trueValue, Integer falseValue) { 
    if (value == null) { 
     if (trueValue == null) { 
      return true; 
     } else if (falseValue == null) { 
      return false; 
     } 
    } else if (value.equals(trueValue)) { 
     return true; 
    } else if (value.equals(falseValue)) { 
     return false; 
    } 
    // no match 
    throw new IllegalArgumentException("The Integer did not match either specified value"); 
} 

只需截斷你的排長，直到你需要在下PARAM進行（或您以其他方式進行）。 Javadoc還支持很多HTML標記，例如預格式化文本的<pre>。當您的文檔對空間敏感時（包括換行符），這非常有用。