Java Reference
In-Depth Information
20.8.8. Documentation Comment Tags
As you can see from the Rectangle code, the serialized form of an object
can be an important thing, separate from its runtime form. This can hap-
pen over time due to evolution, or by initial design when the runtime
form is not a good serialized form. When you write serializable classes
that others will reimplement, you should document the persistent form
so that other programmer's can properly re-implement the serialized
form as well as the runtime behavior. You do this with the special
javadoc tags @serial , @serialField , and @serialData .
Use @serial to document fields that use default serialization. For ex-
ample, the original Rectangle class could have looked like this:
/** X-coordinate of one corner.
* @serial */
private double x1;
/** Y-coordinate of one corner.
* @serial */
private double y1;
/** X-coordinate of opposite corner.
* @serial */
private double x2;
/** Y-coordinate of opposite corner.
* @serial */
private double y2;
The @serial tag can include a description of the meaning of the field. If
none is given (as above), then the description of the runtime field will be
used. The javadoc tool will add all @serial information to a page, known
as the serialized form page.
The @serial tag can also be applied to a class or package with the single
argument include or exclude , to control whether serialization information
is documented for that class or package. By default public and protected
 
Search WWH ::




Custom Search