NOTE: We have implemented a fix for the main problem;
however this fix requires a separate run of Javadoc
with -private flag.  This synopsis of this bug
was changed on April 18, 2000 to indicate completing
the rest of this bug.
.....

The serialized form information given does not
provide enough information to create a fully
compatible set of core classes, as only the
serialized form of public classes is given.

I am writing an implementation of the Collections
classes for a clean room set of class libraries.
The problem lies in methods such as
java.util.Collections.reverseOrder() which return
private inner classes, and then state that their
return value is Serializable. There are a number
of such methods in the Collections class, and
the AbstractList.subList() method is another
(which may not state explicitly that the return
value is serializable, but it certainly ought to
be!)

I don't know whether Collections is the only API
to suffer from this problem, or whether it is
more general. The solution probably requires work
from both the Collections team AND the javadoc
team.

However, it is a major problem for inter-VM RMI
and for JavaBeans. Please spec it, and fast - you
can't afford for this not to make it into the FCS!
(Review ID: 38641)
======================================================================

N/A

Assigned to joe.fialli.  Put Josh and Robert on interest list.
  xxxxx@xxxxx   1998-10-12

Two actions items:
1) run javadoc -private to include private classes in the serialized form 
   page and then strip out the links to other docs
2) turn this into a bug to have the serialization form include private classes
   without requiring the -private option

For #1 above, I added a new gnumake target to 1.2 Docs.gmk called
"releasedocs-serialpage" that creates a tmp directory, generates javadoc 
with -private option, then runs a perl script to strip out all links (except 
in the navigation bar), then copies this file to the docs/api directory
and deletes the tmp directory.
  xxxxx@xxxxx   1998-10-19

The email discussion of this is at:
http://javaweb.eng/docs/writing/central/api-specs/serialized-form-private.html

The list of classes to include are at:
http://javaweb.eng/docs/writing/central/api-specs/serialized-form-private-1.2.html

Changes were made to the Docs.gmk file:
<ws>/build/solaris/makefiles/Docs.gmk

Note this has 18 JDC votes.
  xxxxx@xxxxx   1998-11-09

Robert wants to look at this to see how difficult it would be to fix for 1.2.2
Atul, perhaps you could look at this first, then present it to Robert.
  xxxxx@xxxxx   1998-12-14

Since we don't have time to implement this for inclusion in Javadoc
for Kestrel, Robert suggests that we write a separate doclet to 
perform this task that has a deadline after the Kestrel code
freeze, meaning Atul could perhaps write it in late June or 
July, so it would still be ready for generating the Kestrel FCS docs.  
Then we could fold it into the standard doclet after kestrel FCS, 
when the workspace unfreezes again.
  xxxxx@xxxxx   1999-04-27

We have resolved action item #1 above by adding @serial include
and @serial exclude, running Javadoc with the -private option and
copying serialized-form.html to the normal Javadoc run (without
-private).  I have build this double-run process into the -releasedocs
target of Docs.gmk.  What remains to resolve is action item #2,
which I am doing now:

  Turn this into a bug to have the serialization form include private classes
  without requiring the -private option

Robert says this will be possible with the Javadoc built on the new compiler.
So I changed the synopsis from:
  Serialized form information is incomplete--private classes are missing  

  Allow serialized form to be generated in normal run of Javadoc
  xxxxx@xxxxx   2000-04-25

Can I please have a specification of exactly what you would like to change
in the implementation of the javadoc API?

  xxxxx@xxxxx   2001-02-21

Please see the specification at the bottom of "Suggested Fix".
  xxxxx@xxxxx   2001-02-22

  xxxxx@xxxxx   wrote:

<quote>
The StubMaker doclet has in effect solved this problem.
It processes all the fields and determines if they are
serializable.

If all of the these hold:
  * it is serializable.
  * it is not primitive
  * the class type is hidden (i.e. not visible, as
    defined by the javadoc switches -public, -protected,
    etc.)
  * the classes' package matches one of the packages 
    on the command line

then:
  * the class is added to the list of classes to process.
  * if the class is not serializable, an error is generated
  * if the "@serial include" tag is not present, an error
    is generated
 
In that way, otherwise hidden classes are processed,
but only if they are serializable and included.

The process is of course recursive, so all required classes
are found.

The same algorithm could be added to the standard doclet
to produce a valid Serialized Form, *without* requiring
the use of the -private switch.
</quote>
  xxxxx@xxxxx   2001-02-23

Is there some reason this approach would be inappropriate for the standard
doclet?

  xxxxx@xxxxx   2001-03-02

Eric, Jamie and I just spoke yesterday, and this solution is 
possible.  However, the addition of the allClasses(private)
method would allow the doclet to do an additional check.
Jamie will implement this, but am leaving it assigned to
to implement allClasses(private) or in case you somehow 
determine allClasses(private) is not needed. 
Here is Eric's email: (he also enclosed the source code for
Jamie)

Here is the procedure for generating the serialized
form in the standard doclet, and for detecting developer
errors in the process.

Setup:
  1) Use allClasses() to initialize the collection
     of classes for the serialized form
     --this step gets all visible classes
  2) Run through that collection, removing any
     that have @serial exclude.
  3) Save the excluded classes in a hash table.

Class processing:
  1) Use serializableFields to get the array of
     FieldDocs for serialized fields
  2) If definesSerialPersistentFields() is true
     then the array contains one item, which has
     a special API, otherwise, the array contains
     the default non-transient fields (whether
     hidden or visible). 
  3) Process the array of fields:
       a) FieldDoc.type().asClassDoc() gets the class
       b) If the class is visible, check to see
          if the class is in the excluded table. 
          If it is, generate a warning:
          [[non-transient field uses an excluded
            class]]
       c) If the class is hidden, check to make
          sure it specifies @serial include.
          --if it doesn't, generate a warning:
            [[non-transient field uses a hidden,
              non-included class]]
          --otherwise, add it to the collection of
            of classes for the serialized form
   3) When all other processing is completed, 
      process the collection of classes for the
      serialized form page.         

Additional Error Check
  When allClasses(private) becomes available,
  process the list it returns to do the following:
  1) If the class is visible, ignore it.
  2) If the class is hidden, see if @serial include
     was specified.
  3) If @serial include was specified, see if the
     class was actually used (if it was, it will 
     be in the collection of classes for the
     serialized form page)
  4) If the class is not present in that collection,
     generate a warning:
     [[class specified with @serial include that
       is not used by any serialized field]]

  xxxxx@xxxxx   2001-03-15

As most of the functionality is possible with the current API, I'm
not committing this for Merlin.

  xxxxx@xxxxx   2001-03-19

Neal, Eric and Jamie have concluded that Eric's algorithm
will not work for all cases. (See "Comments" for more details.) 
Therefore, we are requesting to add allClasses(private) to the 
Doclet API to solve this problem.

  xxxxx@xxxxx   2001-05-10

Quite amazing that this little thing has managed to slip for an entire year.