The Source for Java Technology Collaboration
User: Password:
Register | Login help    

Search

Online Books:
java.net on MarkMail:

Sebastien Dionne

Sebastien Dionne graduated from university in Software Engineering. He started his career making rich client applications for telecommunications companies using Swing. Now he is focussing on J2EE applications in banking companies. His job is mainly to provide real-time applications web based and gateways for the stock market.

 

Sebastien Dionne's blog

Extends javadoc with custom tags like @example.

Posted by survivant on November 8, 2009 at 5:14 AM PST
I would like to show you how you could extend your javadoc to include samples directly into the javadoc without extra work.

What I don't like about javadoc is the lack of code sample. Something is can be hard to find the starting point of a new framework.

Let's show a example, it will be easier to understand, and so simple.


 /** 
 *
 * This in a javadoc with a custom tag @example.
 *
 * @author Sebastien Dionne
 *
 * @example.
 * <pre>
 * 
 * SSDPControler controler = new SSDPControler();
 * 
 * // sends messages each 30 seconds.
 * controler.getPeriodicMessageSender().setDelay(30000);
 *
 * controler.setPeriodicMessageSender(new SSDPPeriodicMessageSender(null) {
 *     @Override
 *     public List<String> returnHellos() {
 *         List<String> list = new ArrayList<String>();
 *
 *         list.add("hello1");
 *         list.add("hello2");
 *
 *         return list;
 *     }
 * });
 * controler.start();
 * </pre>
 */
In this example, we used a custom tag @example. The result will look like this.


...
public class SSDPControler
extends Object
implements ISSDPControler
...
This in a javadoc with a custom tag @example.

Example :

    SSDPControler controler = new SSDPControler();
 
    // sends messages each 30 seconds.
    controler.getPeriodicMessageSender().setDelay(30000);
 
    controler.setPeriodicMessageSender(new SSDPPeriodicMessageSender(null) {
       @Override
       public List<String> returnHellos() {
           List<String> list = new ArrayList<String>();
  
           list.add("hello1");
           list.add("hello2");
  
           return list;
       }
   });
   controler.start();
There is a thing that you need to know to avoid surprises :

Javadoc tool will cut the custom tag as soon as it detect another annotation, so don't forget to convert to HTML code like
@ : become : "&"#64;


To acheive that you need to add little config into your pom. Add the lines in bold.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.6.1</version>
    <configuration>
          <links>
            <link>http://java.sun.com/javase/6/docs/api/</link>
          </links>
          <detectOfflineLinks/> 
          
          <tags>
            <tag>
              <name>example.</name>
              <placement>aoptcmf</placement>
              <head>Example :</head>
            </tag>
          </tags>
          
      </configuration>
</plugin>
»
Related Topics >> Community      General      J2EE      Java Tools      Open Source      
Comments
Comments are listed in date ascending order (oldest first)
Syndicate content




 

Feedback  | FAQ  | Terms of Use
Privacy  |  Trademarks | Site Map
 
Your use of this web site or any of its content or software indicates your agreement to be bound by these Terms of Participation.
 
Copyright © 1995-2008 Sun Microsystems, Inc.
Collabnet Logo Cognisync Communities
Powered by Sun Microsystems, Inc.,
CollabNet and Cognisync