Page History

...

1. From the contents of the description tag of the @org.apache.xbean.Property annotation, for example:

   Code Block
   java java
   /** * @org.apache.xbean.Property description="here's my documentation!" */

   This approach works nice and makes it explicit where the documentation comes from. However, the documentation must appear on the same line: this is not good, as it discourages developers from writing detailed documentation and can lead to massively long lines in the code.
2. From the JavaDoc contents of the setter getter method. In the absence of a @org.apache.xbean.Property description tag, xbean will use the JavaDoc of the getter method. This is good, as it means you can have multi-line documentation commentary. However, the kind of documentation most coders put on a getter is typically quite basic, like "returns the delay": this is not going to be appropriate for an XML editting user who wants to know what they are setting.
3. From the JavaDoc contents of the getter setter method. This is arguably the best approach to use: here, you can write multi-line javadoc documentation, that matches the semantics of someone who wants to "set" some value and wants to know more about it.

...

This approach works well; it allows you to specify documentation once that will appear in the xbean generated XSD, HTML & WIKI files, and in any JavaDoc we create.

One issue to resolve note is what happens when your class inherits from another class , and the source is not available as part of the xbean generation stage. For in a separate project; for example, the FilePollerEndpoint in servicemix-file inherits from PollingEndpoint in servicemix-common. As a result, xbean can detect the inherited attributes but cannot locate the xdoclet documentation tags. To get around this I've wrapped the inherited setters to provide the documentation. It's not desirable as a solution (if only xbean used true Java 5 annotations instead of xdoclet); however, it gets the job done.

An example of how to wrap an inherited property is shown below for the FilePollerEndpoint in servicemix-file.

In order for the xbean plugin to pick up the xdoclet annotations from your base class, you should add a source-level dependency in your project's POM, like this.

    <!-- include servicemix-common as a source for the XSD documentation generator -->
    <dependency>
     <groupId>org.apache.servicemix</groupId>
      <artifactId>servicemix-common</artifactId>
      <version>${servicemix-shared-version}</version>
      <classifier>sources</classifier>
      <scope>provided</scope>
      <optional>true</optional>
    </dependency>

/**
 * Sets the number of milliseconds between polling attempts.
 *
 * @param        period  a long specifying the gap between polling attempts
 */
@Override
public void setPeriod(long period) {
	// Note: we only override this method so that we can specify suitable javadoc (above) that can be used
	// to auto-generate XSD document annotations in the resulting XSD file.
	//
	super.setPeriod(period);
}