new Javadoc 5 tags

6 messages

new Javadoc 5 tags

Reply Threaded

Javadoc 5 introduced the {@code} [1] tag which does not interpret HTML
tags. Thus theres no need for escaping HTML entities. We can change code
form this:

<pre class="prettyprint">
<context-param>
<param-name>config-service-class</param-name>
<param-value>com.corp.CustomConfigSerivce</param-value>
</context-param>
</pre>

to this:

<pre class="prettyprint">
{@code
<context-param>
<param-name>config-service-class</param-name>
<param-value>com.corp.CustomConfigSerivce</param-value>
</context-param>
}
</pre>

Its also possible to close and reopen {@code} tags if HTML
interpretation is needed:

<pre class="prettyprint">
{@code
<context-param>
<param-name>}<span class="red">config-service-class</font>{@code
</param-name>
<param-value>com.corp.CustomConfigSerivce</param-value>
</context-param>
}
</pre>

Nice!

[1]:
http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#{@code}

Malcolm Edgar-2

Re: new Javadoc 5 tags

Reply Threaded

That is great, will be much easier to write decent Javadoc.

regards Malcolm Edgar

On Sun, Oct 18, 2009 at 5:38 PM, Bob Schellink <[hidden email]> wrote:

Javadoc 5 introduced the {@code} [1] tag which does not interpret HTML tags. Thus theres no need for escaping HTML entities. We can change code form this:

<pre class="prettyprint">
<context-param>
<param-name>config-service-class</param-name>
<param-value>com.corp.CustomConfigSerivce</param-value>
</context-param>
</pre>

to this:

<pre class="prettyprint">
{@code
<context-param>
<param-name>config-service-class</param-name>
<param-value>com.corp.CustomConfigSerivce</param-value>
</context-param>
}
</pre>

Its also possible to close and reopen {@code} tags if HTML interpretation is needed:

<pre class="prettyprint">
{@code
<context-param>
<param-name>}<span class="red">config-service-class</font>{@code </param-name>
<param-value>com.corp.CustomConfigSerivce</param-value>
</context-param>
}
</pre>

Nice!

[1]: http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#{@code}

Adrian A.

Re: new Javadoc 5 tags

Reply Threaded

In reply to this post by Bob Schellink-2

> Javadoc 5 introduced the {@code} [1] tag which does not interpret HTML
> tags. Thus theres no need for escaping HTML entities. We can change code
> form this:
>
> <pre class="prettyprint">
> <context-param>
> <param-name>config-service-class</param-name>
> <param-value>com.corp.CustomConfigSerivce</param-value>
> </context-param>
> </pre>
>
> to this:
>
> <pre class="prettyprint">
> {@code
> <context-param>
> <param-name>config-service-class</param-name>
> <param-value>com.corp.CustomConfigSerivce</param-value>
> </context-param>
> }
> </pre>

Should we change the javadocs to this new syntax before or after the 2.1
final release?

Adrian.

Bob Schellink-2

Re: new Javadoc 5 tags

Reply Threaded

We can do it before or after, shouldn't matter too much.

Also note in Docbook we can use CDATA to similar effect:

<programlisting language="xml"><![CDATA[<html>
<body>
...
</body>
</html>]]> </programlisting>

regards

bob

Adrian A. wrote:
> Should we change the javadocs to this new syntax before or after the 2.1
> final release?
>
> Adrian.
>
>

Adrian A.

Re: new Javadoc 5 tags

Reply Threaded

> We can do it before or after, shouldn't matter too much.
I've tried it on several classes and I'm not sure at all that it might
be easier with {@code } because:
1. Many IDEs don't seem to "interpret" this tag for quick preview (in
the editor window - so now one needs to build all the time the javadoc
from ANT to see the result of changes}.
2. The code doesn't look more readable to me (for the classes I've
tried)- in fact is much harder now to distinguish between "interpreted"
and "non-interpreted" HTML markup when editing :(.

The problem I see is for the cases where they are mixed - and many of
our code snippets are mixed because of the nice color outline of the
essential parts.

So the question is: should we proceed (than I'll start to check-in) or
not with this kind of change.

Thank you,

Adrian.

Bob Schellink-2

Re: new Javadoc 5 tags

Reply Threaded

If its going to be a problem lets leave it out rather.

kind regards

bob

Adrian A. wrote:

>> We can do it before or after, shouldn't matter too much.
> I've tried it on several classes and I'm not sure at all that it might
> be easier with {@code } because:
> 1. Many IDEs don't seem to "interpret" this tag for quick preview (in
> the editor window - so now one needs to build all the time the javadoc
> from ANT to see the result of changes}.
> 2. The code doesn't look more readable to me (for the classes I've
> tried)- in fact is much harder now to distinguish between "interpreted"
> and "non-interpreted" HTML markup when editing :(.
>
> The problem I see is for the cases where they are mixed - and many of
> our code snippets are mixed because of the nice color outline of the
> essential parts.
>
> So the question is: should we proceed (than I'll start to check-in) or
> not with this kind of change.
>
> Thank you,
>
> Adrian.
>
>