Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-4181283

stddoclet: Cannot add @see links to {read,write}Object

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Resolved
    • Priority: P4
    • Resolution: Cannot Reproduce
    • Affects Version/s: 1.2.2
    • Fix Version/s: None
    • Component/s: tools

      Description

      Name: tb29552 Date: 10/14/98

      When an '@see' tag points to a serialization readObject or writeObject
      method JavaDoc generates a warning and does not generate the corresponding
      HTML link in the 'Serialized Form' file.

      An example is shown below.

      I think this is because the {read,write}Object methods are documented on their own
      page, serializedform.html, and are all on this one page, whatever class they come from.
      From what I have seen, the generated HTML code does not even define specific anchors
      for each method, they are all tagged with <a name="readObject(java.io.ObjectInputStream)">.

      Fixes:
       - The generated HTML code should allow one to refer to a specific implementation of
         a {read,write}Object method.
       - The '@see' tag should know how to generate proper HTML code for this particular case.

      To reproduce this bug put the following two classes in a directory called Serial.
      Then running JavaDoc will produce the following output.

      >%JBIN%\javadoc -sourcepath . -d Serial Serial
      Loading source files for package Serial...
        <... removed some irrelevant lines>
      Generating Serial\serializedform.html...
      javadoc: warning - @see Can't find writeObject(java.io.ObjectOutputStream) =
      in Serial.A.
      javadoc: warning - in class Serial.A, missing @serial tag for default seria=
      lizable field: aField.
      javadoc: warning - @see Can't find readObject(java.io.ObjectInputStream) in=
       Serial.A.
      javadoc: warning - @see Can't find writeObject(java.io.ObjectOutputStream) =
      in Serial.A.
      Generating Serial\help.html...
      Generating Serial\stylesheet.css...
      4 warning

      Also open the "Serial\serializedform.html" file to notice that no HTML
      link has been generated for the @see references.

      --

      package Serial;

      public class A implements java.io.Serializable
      {
          int aField;

          /**
           * Comment on A.writeObject.
           */
          private void writeObject(java.io.ObjectOutputStream out) throws java.io.IOException
          {
          }

          /**
           * Comment on A.readObject.
           * @see #writeObject(java.io.ObjectOutputStream)
           */
          private void readObject(java.io.ObjectInputStream in) throws java.io.IOException, ClassNotFoundException
          {
          }
      }

      --

      package Serial;

      public class B extends A
      {
          /**
           * Comment on B.writeObject.
           * @see A#writeObject(java.io.ObjectOutputStream)
           */
          private void writeObject(java.io.ObjectOutputStream out) throws java.io.IOException
          {
          }

          /**
           * Comment on B.readObject.
           *
           * @see A#readObject(java.io.ObjectInputStream)
           */
          private void readObject(java.io.ObjectInputStream in) throws java.io.IOException, ClassNotFoundException
          {
          }
      }
      (Review ID: 38656)
      ======================================================================

        Attachments

          Activity

            People

            Assignee:
            bpatel Bhavesh Patel (Inactive)
            Reporter:
            tbell Tim Bell
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Dates

              Created:
              Updated:
              Resolved:
              Imported:
              Indexed: