Javadoc Tip: @code and @literal

When writing my javadoc, I like to have keywords and class names appear as code text in the generated HTML. I also have occasion to use "<" and ">" in javadoc, either for their mathematical meaning or for writing type variables in code. In the past I've used

<code>MyClassName</code>
or
<tt>MyClassName</tt>
to implement the former markup and suffer through
<tt>Outer&lt;S&gt;.Innter&lt;T&gt;
to write "Outer<S>.Innter<T>". Fortunately as of JDK 5, the @code and @literal javadoc tags often provide a more concise and readable way to achieve these effects.

Text inside the @literal inline tag is interpreted literally and not as HTML markup. The @code tag is the same except that the result is presented in the code font. Therefore, the above two examples can be written simply as

{@code MyClassName}
and
{@code Outer<S>.Inner<T>}
Even for just putting text into the code font, "{@code }" takes fewer characters than "<tt></tt>", eight versus nine. Not having to escape "<" and ">" is much shorter and greatly more readable.

In new code, I almost exclusively use @code for putting text into the code font; the exceptions include the rare times I want to have code text itself be marked up and large code blocks where <pre></pre> is useful.

Comments:

Post a Comment:
Comments are closed for this entry.
About

darcy

Search

Archives
« July 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
  
       
Today
News

No bookmarks in folder

Blogroll