javadoc of Properties in argument

Question

I have a method that accepts a Properties object. Is there a standard way to document the properties in the javadoc in a way such as:

/**
 * @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

I don't think there is a standard way to document such information. However, I would document it in the description, not under the @param tag. The @param tag should be a short description of the parameter, longer text is better placed elsewhere. For example:

/**
 * 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) { ... }