Since serialization is part of the public API of a class or method, the serialization information should be documented as any other part of the public API.
Fields are tagged with the @serial tag.
/** * Specific details about the Throwable. For example, for * <tt>FileNotFoundException</tt>, this contains the name of * the file that could not be found. * * @serial */ private String detailMessage;
The Javadoc tool adds a See Also reference called Serialized Form that references the so tagged fields. For example the serialized form for the java.lang.Throwable in the API of Java 6.
Methods involved in the serialization process are tagged with the @serialData to describe how instances of this class are serialized.
/**
* Save the state of the <tt>ArrayList</tt> instance to a stream (that
* is, serialize it).
*
* @serialData The length of the array backing the <tt>ArrayList</tt>
* instance is emitted (int), followed by all of its elements
* (each an <tt>Object</tt>) in the proper order.
*/
private void writeObject(java.io.ObjectOutputStream s)
throws java.io.IOException{
The Javadoc tool adds a See Also reference called Serialized Form that references the so tagged methods. For example the serialized form for the java.util.ArrayList in the API of Java 6.