title: Justification for using <code> tags for class names and keywords in Javadocs?
body: <p>In its <a href="http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide" rel="nofollow">style guide</a>, Oracle suggests to use the <code>&lt;code&gt;</code> tags in Javadocs the following cases:</p>
  
  <ul>
  <li>Java keywords </li>
  <li>package names</li>
  <li>class names</li>
  <li>method names</li>
  <li>interface names</li>
  <li>field names</li>
  <li>argument names</li>
  <li>code examples</li>
  </ul>
  
  <p>I personally find the cases of 'class names', 'field names', and 'Java keywords' particularly cumbersome as you end up with descriptions that I find to be less readable. For example:</p>
  
  <pre><code>/**
  * Returns &lt;code&gt;true&lt;/code&gt; if &lt;code&gt;x&lt;/code&gt; is greater than 
  * &lt;code&gt;y&lt;/code&gt; otherwise returns &lt;code&gt;y&lt;/code&gt;.
  */
  public Boolean greaterThan(int x, int y) { return (x &gt; y); }
  </code></pre>
  
  <p>I realize that the above example is arbitrary in itself, but longer descriptions for more complex functions can ends up equally ugly.  I understand the goal is to make the description pretty in an IDE, but looking at the class' java file itself is painful.</p>
  
  <p>I'm considering foregoing <code>&lt;code&gt;</code> tags except when the documentation will contain a full fledged code example.  Are there reasons to not do this that I'm missing?</p>