Child pages
  • Wonder Javadoc

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: some corrections, add Javadoc images
Note

This page is work in progress.

 

This page presents thoughts and suggestions for creating and maintaining Javadocs in Wonder and should evolve to some sort of Javadoc coding standard.

...

All public and protected methods should be fully defined with Javadoc. Exception may be when a method is a simple getter or setter where a description would not add any information though it does no harm to do so. Package and private methods do not have to be documented, but may benefit from it. Methods that override another method should not have Javadocs except if their description would differ from the original one and include important additional information.

...

Code Block
languagejava
/** compressed Javadoc comment */ 
public …

...

Note

Do not end a Javadoc comment with '**/' and do not start non-Javadoc comments with '/**'.

HTML usage

Use simple HTML tags if you need to add styling to the Javadoc. Don't use XHTML as that will only add unnecessary complexity and the Javadoc parser is expecting simple HTML anyways.

...

For the keywords null, true and false you should not use code tags as those keywords are very common in Javadoc and thus this would add much unnecessary code to Javadoc comments.

...

There are some tags that should always be included if appropriate.

Class documentation

...

A class using generic type parameters should also have @param tags with a parameter name of <T> where T is the type parameter name.

...

If the method throws exceptions you have to document them too with a @throws tag for every thrown type.

A method using generic type parameters should also have @param tags with a parameter name of <T> where T is the type parameter name.

...

Code Block
languagejava
/**
 * Returns the one object that matches the qualifier in the given array (or
 * null if there is no match).
 *
 * @param <T> the type of the objects
 * @param array the array to filter
 * @param qualifier the qualifier to filter onwith
 * @return one matching object or null
 * @throws IllegalStateException if more than one object matched
 */
public static <T> T one(NSArray<T> array, EOQualifier qualifier) { … }

...

Code Block
languagejava
/**
 * Cover method for returning a float for a given system property.
 *
 * @param key system property
 * @return float value of the system property or 0
 */
public static float floatForKey(String key) { … }

As soon as you add the second language like Japanese you should convert this to the following form:

Code Block
languagejava
/**
 * <div class="en">Cover method for returning a float for a given system property.</div>
 * <div class="ja">システム・プロパティーの結果を float で戻します</div>
 *
 * @param key <div class="en">system property</div>
 *            <div class="ja">キー(システム・プロパティー内)</div>
 * @return float <div class="en">value>float value of the system property or 0</div>
 *               <div class="ja">値、デフォルトは>float 値、デフォルトは 0</div>
 */
public static float floatForKey(String key) { … }

You need to enclose the blocks for every language with a div tag and set a class attribute corresponding to the locale code, i.e. en for English and ja for Japanese. Those classes will be used in the generated Javadoc HTML pages to let the user switch between languages to display.

default Javadoc overlay in EclipseJavadoc overlay with multiple languages in Eclipse
default Javadoc overlay in EclipseImage AddedJavadoc overlay with multiple languages in EclipseImage Added
Info

It should be checked if it is possible to add functionality to WOLips to be able to choose the displayed Javadoc language within Eclipse tooltips so even if multiple languages are defined in the Javadocs only a specific one is displayed. Any volunteers? (smile)

Multi-language Javadoc update

If a method has a multi-language Javadoc and someone is changing modifying text in only one of those languages then we need a marker signaling that a specific language needs yet to be updated. For that all affected div blocks should be tagged with an additional CSS class needs_update and have an '!' inserted at the beginning of their contents. Lets say the above Javadoc for floatForKey has been updated to reflect some changes in the method:

Code Block
languagejava
/**
 * <div class="en">Cover method for returning a float for a given system property prefixed with "test.".</div>
 * <div class="ja needs_update">!システム・プロパティーの結果を float で戻します</div>
 *
 * @param key <div class="en">system property</div>
 *            <div class="ja">キー(システム・プロパティー内)</div>
 * @return float <div class="en">value>float value of the prefixed system property or 0</div>
 *               <div class="ja needs_update">!float 値、デフォルトは 0</div>
 */
public static float floatForKey(String key) { … }

The English method and return descriptions have been altered and thus both corresponding Japanese div blocks got the second additional CSS class needs_update. As the param description for key didn't change no CSS class was added there. This By this it is making it possible to search for those Javadocs Javadoc pieces that need to be updated later on . As by anyone who is proficient in both languages. But as those CSS classes are not visible within the tooltips of Eclipse we need the inserted to insert a '!' character to the text so the user gets visual feedback that the description may be inexact.