使用<code> tags for class names and keywords in Javadocs?</code>的理由

Question

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

• Java关键字
• 包名称
• 班级名称
• 方法名称
• 接口名称
• 字段名称
• 参数名称
• 代码示例

我个人发现'类名'，'字段名'和'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;
}