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

Javadocs treatment of @literal tag is inconsistent with previous behavior.

    Details

    • Type: Bug
    • Status: Open
    • Priority: P4
    • Resolution: Unresolved
    • Affects Version/s: 8u45
    • Fix Version/s: tbd_minor
    • Component/s: tools
    • Labels:

      Description

      FULL PRODUCT VERSION :
      java version "1.8.0_45"
      Java(TM) SE Runtime Environment (build 1.8.0_45-b14)
      Java HotSpot(TM) 64-Bit Server VM (build 25.45-b02, mixed mode)

      ADDITIONAL OS VERSION INFORMATION :
      Microsoft Windows [Version 6.1.7601]

      A DESCRIPTION OF THE PROBLEM :
      Javadocs now treats the {@literal} tag differently than before, and the new behavior is more restrictive, less useful, and not described in the documentation.

      When I use the @literal tag inside a <pre></pre> block, it treats the space that follows "literal" as part of the literal text, whereas in earlier versions of the JDK, it (correctly, in my view) treated the space as a separator.

      I'm not sure if this change was intentional, but it's a bad idea, because it's inconsistent with past behavior, and it forces me to misalign the code in my source file in order to see text that is aligned properly in the javadocs output.

      When generate javadocs under JDK 1.7 or earlier, everything that is aligned in the source code will also be aligned in the Javadoc output, as it should be.

      When I generate javadocs under JDK 1.8, things get misaligned. This is because the space that follows the word "literal" is interpreted as part of the documentation, instead of being the separator between "literal" and the text to operate on. This makes no sense, and it causes problems:

      1. It forces me to rewrite lots of javadocs if I want it formatted correctly.
      2. The only way to get the blocks of code to be aligned properly is to misalign them in my source. (I can remove a space before the literal tag.) This makes my javadocs code look sloppy and unprofessional.
      3. If I do so, other team members may see the misalignment as sloppy and realign them, which will mess up the javadocs.
      4. Since a space after "literal" is required, there is no longer any way to put in a @literal tag that's not followed by a space in the javadocs output, as there was before.

      In short, this change gives me no new capabilities, and reduces my flexibility.

      The general principle that people are likely to assume is that things that are aligned in the source code should remain aligned in the javadocs.

      Since I couldn't find anything in the documentation describing this new behavior, I'm assuming it's a bug that should be fixed. I shouldn't have to rewrite my otherwise properly formatted javadocs code when upgrading to a new version of Java.

      However, this may be an intentional change that sounded like a good idea before anyone tried it out. I think it's a terrible idea.

      REGRESSION. Last worked in version 7u80

      ADDITIONAL REGRESSION INFORMATION:
      Worked in:
      java version "1.7.0_40"
      Java(TM) SE Runtime Environment (build 1.7.0_40-b43)
      Java HotSpot(TM) 64-Bit Server VM (build 24.0-b56, mixed mode)

      Fails in:
      java version "1.8.0_45"
      Java(TM) SE Runtime Environment (build 1.8.0_45-b14)
      Java HotSpot(TM) 64-Bit Server VM (build 25.45-b02, mixed mode)

      STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
      Generate javadocs for the supplied source code.

      EXPECTED VERSUS ACTUAL BEHAVIOR :
      EXPECTED -
      Text that is aligned in the source should be aligned in Javadocs.

      Text that is misaligned in the source should be misaligned in Javadocs.

      The tag with the missing space {@literal@Test} will fail to appear in Javadocs. This works correctly, and illustrates that the space is a necessary part of the @literal tag, and does not belong in the javadocs output.
      ACTUAL -
      Text that is aligned in the source is misaligned in Javadocs.

      Text that is misaligned in the source is properly aligned in Javadocs.

      REPRODUCIBILITY :
      This bug can be reproduced always.

      ---------- BEGIN SOURCE ----------
      /* Generate javadocs for the following annotation: */

      import java.lang.annotation.Retention;
      import java.lang.annotation.RetentionPolicy;

      /**
       * Specify the execution order of unit tests. Intended primarily for FEST testing. This only works when
       * run with the OrderedRunner:
       * <pre>
       * {@literal @Test} // properly aligned block in source
       * {@literal @Order(order = 10)}
       * public void testCreate1() { ... }
       *
       *{@literal @Test} // misaligned block in source
       *{@literal @Order(order = 20)} // Other developers will see this as a mistake and "correct" it.
       * public void testCreate2() { ... }
       *
       * {@literal@Test} (annotation on this line shouldn't work)
       * {@literal @Order(order = 30)}
       * public void testDelete() { ... }
       * </pre>
       * @see OrderedRunner
       */
      @Retention(RetentionPolicy.RUNTIME)
      public @interface Order {
          int order();
      }

      ---------- END SOURCE ----------

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                Unassigned
                Reporter:
                webbuggrp Webbug Group
              • Votes:
                0 Vote for this issue
                Watchers:
                4 Start watching this issue

                Dates

                • Created:
                  Updated: