java - 在 Javadocs 中使用 标签作为类名和关键字的理由？

Question

在其style guide , Oracle 建议使用 <code>在 Javadocs 中标记以下情况:

• Java 关键字
• 包名
• 类名
• 方法名
• 接口(interface)名称
• 字段名称
• 参数名称
• 代码示例

我个人认为“类名”、“字段名”和“Java 关键字”的情况特别麻烦，因为您最终得到的描述我觉得可读性较差。例如:

/**
* Returns <code>true</code> if <code>x</code> is greater than 
* <code>y</code> otherwise returns <code>y</code>.
*/
public Boolean greaterThan(int x, int y) { return (x > y); }

我意识到上面的例子本身是任意的，但是对更复杂的函数的更长的描述可能会同样丑陋。我知道目标是在 IDE 中使描述更漂亮，但是查看类的 java 文件本身很痛苦。

我正在考虑前述<code>标签，除非文档将包含完整的代码示例。是否有我缺少的不这样做的理由？

Answer 1

• JavaDoc 适用于 JavaDoc (和IDE)。没有其他的。使它成为尽可能可读，因此请为您列出的内容使用代码标签。
• 其他代码注释 应该有助于理解代码。由于它只是代码的一部分，并且只会与代码一起显示，因此不需要进一步的标记。

例子:

/**
 * This method returns <code>true</code> when the sun is shining.
 *
 * @param weather - A <code>package.name.Weather</code> implementation
 * representing the weather to be analyzed.
 * return <code>true</code> if the sun is shining, else <code>false</code>.
 */
public boolean isSunShining(Weather weather) {
    boolean result = false; // boolean variable for the result. Default is false.
    // some more code
    /*
     * Multiline comment w/o markup
     */
    return result;
}