I can't find any information on whether or not it is ok to have multiple lines of info in a javadoc param. I'm making a chess engine and I want to be able to parse a string to generate a board. Is it ok to do it as I've done below?
/**
* 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"
*/
Edit: This has been marked as a duplicate. The reason I believe it is not a duplicate is because the other question is simply about creating a multiline javadoc comment, while this one is about having multiple lines as part of the param argument.
The correct approach is an @param tag with the parameter name of <T> where T is the type parameter name. There should be one blank line between the Javadoc text and the first @param or @return. This aids readability in source code. The @param and @return should be treated as phrases rather than complete sentences.
I'd say that the way you've done it is fine (Edit: Oh, maybe not. Looks like you need a good serving of <pre>
if you want to maintain that particular formatting. Fortunately, the answer still works!).
Consider an expert-grade example from 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");
}
Just truncate your long lines and carry on until you need the next param (or you're otherwise done). Javadoc also supports a lot of HTML tags, such as <pre>
for pre-formatted text. That's useful when your documentation is spacing-sensitive (including newlines).
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With