[Yanel-dev] Javadoc tips (was: Re: [Yanel-commits] rev 48215 - public/yanel/trunk/src/impl/java/org/wyona/yanel/impl/navigation)

[Guillaume Déflache]

memo at wyona.com schrieb:
> Author: memo
> Date: 2010-03-22 16:51:38 +0100 (Mon, 22 Mar 2010)
> New Revision: 48215
> 
> Modified:
>    public/yanel/trunk/src/impl/java/org/wyona/yanel/impl/navigation/SitetreeDOMImpl.java
> Log:
> javadoc fixed
> 
> Modified: public/yanel/trunk/src/impl/java/org/wyona/yanel/impl/navigation/SitetreeDOMImpl.java
> ===================================================================
> --- public/yanel/trunk/src/impl/java/org/wyona/yanel/impl/navigation/SitetreeDOMImpl.java	2010-03-22 15:50:36 UTC (rev 48214)
> +++ public/yanel/trunk/src/impl/java/org/wyona/yanel/impl/navigation/SitetreeDOMImpl.java	2010-03-22 15:51:38 UTC (rev 48215)
> @@ -27,20 +27,25 @@
>  import org.w3c.dom.NodeList;
>  
>  /**
> - * Based on DOM, whereas persistance is done through the src configuration, for example within realm.xml
> - * <repo-navigation class="org.wyona.yanel.impl.navigation.SitetreeDOMImpl">
> - *   <src>data-repo/data/sitetree.xml</src>
> - * </repo-navigation>
> + * Based on DOM, whereas persistance is done through the <code>src</code> configuration, for example within <code>realm.xml</code>
> + * <pre>
> + * &lt;repo-navigation class="org.wyona.yanel.impl.navigation.SitetreeDOMImpl">
> + *   &lt;src>data-repo/data/sitetree.xml&lt;/src>
> + * &lt;/repo-navigation>
> + * </pre>

Using <pre>{@code ...}</pre> (cf. 
<http://java.sun.com/javase/6/docs/technotes/tools/windows/javadoc.html#@code>) 
instead would allow to not escape the tags, making the whole thing more 
readable from the source code.


>   *
> - * or .yanel-rc
> + * or <code>.yanel-rc</code>
>   *
> - * <yanel:custom-config>
> - *   <s:repo-navigation xmlns:s="http://www.wyona.org/yanel/sitetree-dom-impl/1.0" class="org.wyona.yanel.impl.navigation.SitetreeDOMImpl">
> - *     <s:src>yanelrepo:/sitetree.xml</s:src>
> - *   </s:repo-navigation>
> - * </yanel:custom-config>
> + * <pre>
> + * &lt;yanel:custom-config>
> + *   &lt;s:repo-navigation xmlns:s="http://www.wyona.org/yanel/sitetree-dom-impl/1.0" class="org.wyona.yanel.impl.navigation.SitetreeDOMImpl">
> + *     &lt;s:src>yanelrepo:/sitetree.xml&lt;/s:src>
> + *   &lt;/s:repo-navigation>
> + * &lt;/yanel:custom-config>
> + * </pre>

Ditto here.


>   *
> - * Please note that the class org.wyona.yanel.core.map.Realm is using the RealmConfigPathResolver whereas that a resource might use a different resolver implementation!
> + * Please note that the class <code>org.wyona.yanel.core.map.Realm</code> 
> + * is using the <code>RealmConfigPathResolver</code> whereas that a resource might use a different resolver implementation!

When one references a Java name for the 1st time, a link is even better, 
e.g.
- {@link org.wyona.yanel.core.map.Realm}
or
- {@link org.wyona.yanel.core.map.RealmConfigPathResolver 
RealmConfigPathResolver}
(cf. 
<http://java.sun.com/javase/6/docs/technotes/tools/windows/javadoc.html#@link>)

> [...]