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