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

javadoc sentence is parsed differently when html or javadoc tag is used

XMLWordPrintable

      FULL PRODUCT VERSION :
      java version "1.8.0_144"
      Java(TM) SE Runtime Environment (build 1.8.0_144-b01)
      Java HotSpot(TM) 64-Bit Server VM (build 25.144-b01, mixed mode)

      ADDITIONAL OS VERSION INFORMATION :
      Linux MiWiFi-R1CM-srv 3.10.0-514.26.2.el7.x86_64 #1 SMP Tue Jul 4 15:04:05 UTC 2017 x86_64 x86_64 x86_64 GNU/Linux

      A DESCRIPTION OF THE PROBLEM :
      The first Doc#firstSentenceTags() returns different number of tags when we use html tag or javadoc tag in it.

      STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
      1) add javadoc with html tag to one field (e.z. "The {@code ++} (postfix increment) operator.");
      2) add the same javadoc but replacing html tag by javadoc tag to the second filed (e.z. "The <code>++</code> (postfix increment) operator.");
      3) Parse javadoc into RootDoc;
      4) Compare the results of Doc#firstSentenceTags()

      EXPECTED VERSUS ACTUAL BEHAVIOR :
      EXPECTED -
      number of tags is equal when javadoc is used, it is represented as three tags instead of one when html tag is used
      ACTUAL -
      number of tags is different when javadoc is used, it is represented as three tags instead of one when html tag is used.

      ERROR MESSAGES/STACK TRACES THAT OCCUR :
      no error occurs

      REPRODUCIBILITY :
      This bug can be reproduced always.

      ---------- BEGIN SOURCE ----------
      //should be located accessible to test class
      /**
       * The {@code ++} (postfix increment) operator.
       */
      public class JavadocParseError {
          /**
           * The <code>++</code> (postfix increment) operator.
           */
          public static final String CONST = "abc";
      }

      public class JavadocParseTest {

          @Test
          public void testJavadocParsedIncorrectly() throws Exception {
              final ListBuffer<String[]> options = new ListBuffer<>();
              options.add(new String[] {"-destfile", "target/tokentypes.properties"});

              final ListBuffer<String> names = new ListBuffer<>();
              names.add("JavadocParseError.java");

              final Context context = new Context();
              new TestMessager(context);
              final JavadocTool javadocTool = JavadocTool.make0(context);
              final RootDoc rootDoc = getRootDoc(javadocTool, options, names);
              final ClassDoc[] classes = rootDoc.classes();
              assertEquals("Should parse first sentence: " + classes[0].fields()[0].commentText()
                              + "- into one tag. Actual tags: "
                              + Arrays.toString(classes[0].fields()[0].firstSentenceTags()),
                      1, classes[0].fields()[0].firstSentenceTags().length);
              assertEquals("Should parse first sentence: " + classes[0].commentText()
                              + "- into one tag. Actual tags: "
                              + Arrays.toString(classes[0].firstSentenceTags()),
                      1, classes[0].firstSentenceTags().length);
          }

          private static RootDoc getRootDoc(JavadocTool javadocTool, ListBuffer<String[]> options,
                                            ListBuffer<String> names) throws Exception {
              final Method getRootDocImpl = getMethodGetRootDocImplByReflection();
              return (RootDoc) getRootDocImpl.invoke(javadocTool, "", "UTF-8",
                          new ModifierFilter(ModifierFilter.ALL_ACCESS),
                          names.toList(),
                          options.toList(),
                          new ListBuffer<JavaFileObject>().toList(),
                          false,
                          new ListBuffer<String>().toList(),
                          new ListBuffer<String>().toList(),
                          false, false, false);
          }

          private static Method getMethodGetRootDocImplByReflection() throws ClassNotFoundException {
              Method result = null;
              final Class<?> javadocToolClass = Class.forName("com.sun.tools.javadoc.JavadocTool");
              final Method[] methods = javadocToolClass.getMethods();
              for (Method method: methods) {
                  if ("getRootDocImpl".equals(method.getName())) {
                      result = method;
                  }
              }
              return result;
          }

          private static class TestMessager extends Messager {

              private final List<String> messages = new ArrayList<>();

              TestMessager(Context context) {
                  super(context, "");
              }

              @Override
              public void printError(String message) {
                  messages.add(message);
              }
          }
      }
      ---------- END SOURCE ----------

      CUSTOMER SUBMITTED WORKAROUND :
      We need to check that number of tags is not greater than 1, for that purpose we can skip all "Text" tags from validation or just stay with html tags.

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

              Created:
              Updated:
              Resolved: