参数中的属性的javadoc

Question

我有一个接受Properties对象的方法。有没有一种标准的方法来记录javadoc中的属性，例如：

/**
 * @param props containing the following optional configuration props
 *    "one" -> defaults "hello"
 *    "two" -> defaults "bye"
 */
public readProps(Properties props) {
    one = props.getProperty("one", "hello");
    two = props.getProperty("two", "bye");
}

Answer 1

我认为没有一种标准方法来记录此类信息。但是，我会在说明中记录它，而不是在@param标记下。 @param标记应该是参数的简短描述，较长的文本最好放在其他地方。例如：

/**
 * Reads props.
 * A {@link Properties} object is passed to this method containing the 
 * following properties:
 * <dl>
 * <dt>one</dt>
 * <dd>first property, defaults to <code>"hello"</code></dd>
 * <dt>two</dt>
 * <dd>second property, defaults to <code>"bye"</code></dd>
 * </dl>
 *
 * @param props the properties
 */
 public void readProps(Properties props) { ... }