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

stddoclet: Netscape 4 bug causes no blank line between description & tag section

XMLWordPrintable

    • Icon: Bug Bug
    • Resolution: Fixed
    • Icon: P5 P5
    • 1.4.0
    • 1.4.0
    • tools
    • beta
    • generic
    • generic
    • Verified

      While you're fixing the standard doclet, could you implement a workaround for a
      longstanding bug in Netscape 4 that affects comment formatting? The problem is
      that Netscape doesn't insert whitespace after a paragraph in a definition list
      unless that paragraph ends with </p>.

      Adding a blank line is aesthetically desireable, because it creates a visual
      separation between the description section and the tag section. Without
      the blank line, if the description has multiple paragraphs (each separated
      by blank lines), the last paragraph currently visually appears to be bound
      to the tag section.

      More specifically, there is no blank line before "Parameters" in the example
      below, because in Netscape 4, the combination <DD><DL><DT> does not cause a
      blank line to be created.

      <DL>
        <DD>Constructs a newly allocated <code>Integer</code> object that
         represents the <code>int</code> value indicated by the
         <code>String</code> parameter. The string is converted to an
         <code>int</code> value in exactly the manner used by the
         <code>parseInt</code> method for radix 10.
         <p>
         If the radix is smaller than <code>Character.MIN_RADIX</code>
         or larger than <code>Character.MAX_RADIX</code>, then the radix
         <code>10</code> is used instead.

        <DD><DL>
           <DT><B>Parameters:</B>
           <DD><CODE>s</CODE> - the <code>String</code> to be converted to an
                        <code>Integer</code>.
           </DL>
        </DD>
      </DL>


      Simplified, this looks like:

      <DL>
        <DD>text
        <DD><DL>
           <DT><B>Parameters</B>
           </DL>
        </DD>
      </DL>


      The first proposal would be to add pair <P> and </P> around the text:

      <DL>
        <DD><P>text
        </P>
        <DD><DL>
           <DT><B>Parameters</B>
           </DL>
        </DD>
      </DL>


      However, it is equivalent and clearer (and more like other javadoc markup)
      to add <P> only after the text:

      <DL>
        <DD>text
        <P>
        <DD><DL>
           <DT><B>Parameters</B>
           </DL>
        </DD>
      </DL>

            jhosunw Jamie Ho (Inactive)
            jhosunw Jamie Ho (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

              Created:
              Updated:
              Resolved:
              Imported:
              Indexed: