在 Javadoc 中使用 <code> 标签作为类名和关键字的理由是什么？

Question

在其风格指南<code>中，Oracle 建议在以下情况下使用Javadoc 中的标签：

• 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;
}