web-dev-qa-db-ja.com

Javadocのparamタグに複数の行を入れる正しい方法は何ですか？

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コメントを作成することに関するものであり、これはparam引数の一部として複数行を使用することに関するものだからです。

javajavadocdoxygen
9
Tejas Sharma

私はあなたがそれをした方法は良いと思います（編集：ああ、多分そうではありません。その特定のフォーマットを維持したいのであれば<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は、事前にフォーマットされたテキスト用の<pre>など、多くのHTMLタグもサポートしています。これは、ドキュメントが間隔に敏感な場合（改行を含む）に役立ちます。

9
nasukkin