将多行放在 Javadoc 的参数标记中的正确方法是啥？

Posted 2023-03-05

【中文标题】将多行放在 Javadoc 的参数标记中的正确方法是啥？

【英文标题】：What is the correct way put multiple lines in a param tag for a Javadoc?将多行放在 Javadoc 的参数标记中的正确方法是什么？

【发布时间】：2017-01-18 02:58:00

【问题描述】：

我找不到任何关于是否可以在 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 注释，而这个问题是关于将多行作为参数参数的一部分。

【参考方案1】：

我想说你这样做的方式很好（编辑：哦，也许不是。看起来你需要一个很好的 <pre> 服务如果你想保持这种特定的格式。幸运的是，答案仍然作品！）。

考虑一个来自 Apache Commons 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");

只需截断你的长行并继续，直到你需要下一个参数（或者你已经完成了）。 Javadoc 还支持很多 html 标签，例如用于预格式化文本的<pre>。当您的文档对间距敏感（包括换行符）时，这很有用。