JDK-8080797 : Javadocs treatment of @literal tag is inconsistent with previous behavior.
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 8u45
  • Priority: P4
  • Status: Open
  • Resolution: Unresolved
  • OS: windows_7
  • CPU: x86_64
  • Submitted: 2015-05-20
  • Updated: 2018-10-23
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
tbd_minorUnresolved
Related Reports
Relates :  
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 ----------


Comments
The liberal use of multiple @literal tags inside <pre> is not wrong but is stylistically undesirable and difficult to accommodate. The general intent is to allow <pre>{@literal lots of lines of literal text }</pre>
27-05-2015

The change in behavior was deliberate and was for exactly the same reasons as quoted here, to allow alignment in the source code. See JDK-8002387 for examples of why the change was made. So, it seems like there is no one right answer that suits everyone.
27-05-2015

Introduced in jdk8-b91 changeset http://hg.openjdk.java.net/jdk8u/jdk8u/langtools/rev/38c4bade0ec1 The issue is at: http://hg.openjdk.java.net/jdk8u/jdk8u/langtools/rev/38c4bade0ec1#l1.51
27-05-2015