使用<；代码>；Javadocs中类名和关键字的标记？

在its中，Oracle建议在以下情况下在Javadocs中使用

标记：


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文件本身是痛苦的

我正在考虑前面的
标记，除非文档中包含完整的代码示例。我不知道有什么理由不这样做吗？

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


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

我同意你的观点，总的来说，我认为计算机的排版标准通常是令人震惊的，但这个问题并不适合这样做，因为它基本上只会引发“辩论、争论、投票或广泛的讨论”。投票结束是没有建设性的。我想我可以稍微改变一下问题的措辞；我意识到我走的很好。也就是说，我在寻找具体的理由来决定我的决策，而不是辩论。例如，如果你使用
，你将获得x、y和z的好处。（注意，你可以使用
{@code…}
代替
。
），而你可以使用true，如果你使用
你将获得Courier，它更易于阅读。时期没有其他影响。这是否有益是一个完全主观的问题。我同意你的观点，总的来说，我认为围绕计算的排版标准通常是令人震惊的，但这个问题并不适合这样做，因为它基本上只会引发“辩论、争论、投票或广泛讨论”。投票结束是没有建设性的。我想我可以稍微改变一下问题的措辞；我意识到我走的很好。也就是说，我在寻找具体的理由来决定我的决策，而不是辩论。例如，如果你使用
，你将获得x、y和z的好处。（注意，你可以使用
{@code…}
代替
。
），而你可以使用true，如果你使用
你将获得Courier，它更易于阅读。时期没有其他影响。这是否有益是一个完全主观的问题。