1 /*
   2  * Copyright (c) 2009, 2019, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.
   8  *
   9  * This code is distributed in the hope that it will be useful, but WITHOUT
  10  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  11  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  12  * version 2 for more details (a copy is included in the LICENSE file that
  13  * accompanied this code).
  14  *
  15  * You should have received a copy of the GNU General Public License version
  16  * 2 along with this work; if not, write to the Free Software Foundation,
  17  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  18  *
  19  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  20  * or visit www.oracle.com if you need additional information or have any
  21  * questions.
  22  */
  23 
  24 /*
  25  * @test
  26  * @bug 6786690 6820360 8025633 8026567 8175200 8183511 8186332 8074407 8182765
  27  * @summary This test verifies the nesting of definition list tags.
  28  * @author Bhavesh Patel
  29  * @library ../../lib
  30  * @modules jdk.javadoc/jdk.javadoc.internal.tool
  31  * @build javadoc.tester.*
  32  * @run main TestHtmlDefinitionListTag
  33  */
  34 
  35 import java.util.ArrayList;
  36 import java.util.Arrays;
  37 import java.util.List;
  38 
  39 import javadoc.tester.JavadocTester;
  40 
  41 public class TestHtmlDefinitionListTag extends JavadocTester {
  42 
  43     public static void main(String... args) throws Exception {
  44         TestHtmlDefinitionListTag tester = new TestHtmlDefinitionListTag();
  45         tester.runTests();
  46     }
  47 
  48     @Test
  49     public void test_Comment_Deprecated() {
  50 //        tester.run(ARGS1, TEST_ALL, NEGATED_TEST_NO_C5);
  51 //        tester.runTestsOnHTML(NO_TEST,  NEGATED_TEST_C5);
  52 //        tester.runTestsOnHTML(TEST_CMNT_DEPR, NO_TEST);
  53         javadoc("-Xdoclint:none",
  54                 "-d", "out-1",
  55                 "-sourcepath", testSrc,
  56                 "pkg1");
  57         checkExit(Exit.OK);
  58         checkCommon(true);
  59         checkCommentDeprecated(true);
  60     }
  61 
  62     @Test
  63     public void test_NoComment_Deprecated() {
  64 //        tester.run(ARGS2, TEST_ALL, NEGATED_TEST_NO_C5);
  65 //        tester.runTestsOnHTML(NO_TEST,  NEGATED_TEST_C5);
  66 //        tester.runTestsOnHTML(NO_TEST, TEST_CMNT_DEPR);
  67         javadoc("-Xdoclint:none",
  68                 "-d", "out-2",
  69                 "-nocomment",
  70                 "-sourcepath", testSrc,
  71                 "pkg1");
  72         checkExit(Exit.OK);
  73         checkCommon(true);
  74         checkCommentDeprecated(false); // ??
  75     }
  76 
  77     @Test
  78     public void test_Comment_NoDeprecated() {
  79 //        tester.run(ARGS3, TEST_ALL, NEGATED_TEST_NO_C5);
  80 //        tester.runTestsOnHTML(TEST_NODEPR, TEST_NOCMNT_NODEPR);
  81         javadoc("-Xdoclint:none",
  82                 "-d", "out-3",
  83                 "-nodeprecated",
  84                 "-sourcepath", testSrc,
  85                 "pkg1");
  86         checkExit(Exit.OK);
  87         checkCommon(false);
  88         checkNoDeprecated();
  89         checkNoCommentNoDeprecated(false);
  90     }
  91 
  92     @Test
  93     public void testNoCommentNoDeprecated() {
  94 //        tester.run(ARGS4, TEST_ALL, NEGATED_TEST_NO_C5);
  95 //        tester.runTestsOnHTML(TEST_NOCMNT_NODEPR, TEST_CMNT_DEPR);
  96         javadoc("-Xdoclint:none",
  97                 "-d", "out-4",
  98                 "-nocomment",
  99                 "-nodeprecated",
 100                 "-sourcepath", testSrc,
 101                 "pkg1");
 102         checkExit(Exit.OK);
 103         checkCommon(false);
 104         checkNoCommentNoDeprecated(true);
 105         checkCommentDeprecated(false);
 106     }
 107 
 108     void checkCommon(boolean checkC5) {
 109         // Test common to all runs of javadoc. The class signature should print
 110         // properly enclosed definition list tags and the Annotation Type
 111         // Optional Element should print properly nested definition list tags
 112         // for default value.
 113         checkOutput("pkg1/C1.html", true,
 114                 "<pre>public class <span class=\"typeNameLabel\">C1</span>\n" +
 115                 "extends java.lang.Object\n" +
 116                 "implements java.io.Serializable</pre>");
 117         checkOutput("pkg1/C4.html", true,
 118                 "<dl>\n" +
 119                 "<dt>Default:</dt>\n" +
 120                 "<dd>true</dd>\n" +
 121                 "</dl>");
 122 
 123         // Test for valid HTML generation which should not comprise of empty
 124         // definition list tags.
 125         List<String> files= new ArrayList<>(Arrays.asList(
 126             "pkg1/package-summary.html",
 127             "pkg1/C1.html",
 128             "pkg1/C1.ModalExclusionType.html",
 129             "pkg1/C2.html",
 130             "pkg1/C2.ModalType.html",
 131             "pkg1/C3.html",
 132             "pkg1/C4.html",
 133             "overview-tree.html",
 134             "serialized-form.html"
 135         ));
 136 
 137         if (checkC5)
 138             files.add("pkg1/C5.html");
 139 
 140         for (String f: files) {
 141             checkOutput(f, false,
 142                     "<dl></dl>",
 143                     "<dl>\n</dl>");
 144         }
 145     }
 146 
 147     void checkCommentDeprecated(boolean expectFound) {
 148         // Test for normal run of javadoc in which various ClassDocs and
 149         // serialized form should have properly nested definition list tags
 150         // enclosing comments, tags and deprecated information.
 151         checkOutput("pkg1/package-summary.html", expectFound,
 152                 "<dl>\n" +
 153                 "<dt><span class=\"simpleTagLabel\">Since:</span></dt>\n" +
 154                 "<dd>JDK1.0</dd>\n" +
 155                 "</dl>");
 156 
 157         checkOutput("pkg1/C1.html", expectFound,
 158                 "<dl>\n"
 159                 + "<dt><span class=\"simpleTagLabel\">Since:</span></dt>\n"
 160                 + "<dd>JDK1.0</dd>\n"
 161                 + "<dt><span class=\"seeLabel\">See Also:</span></dt>\n"
 162                 + "<dd><a href=\"C2.html\" title=\"class in pkg1\"><code>"
 163                 + "C2</code></a>, \n"
 164                 + "<a href=\"../serialized-form.html#pkg1.C1\">"
 165                 + "Serialized Form</a></dd>\n"
 166                 + "</dl>",
 167                 "<dl>\n"
 168                 + "<dt><span class=\"simpleTagLabel\">Since:</span></dt>\n"
 169                 + "<dd>1.4</dd>\n"
 170                 + "<dt><span class=\"seeLabel\">See Also:</span></dt>\n"
 171                 + "<dd><a href=\"#setUndecorated(boolean)\">"
 172                 + "<code>setUndecorated(boolean)</code></a></dd>\n"
 173                 + "</dl>",
 174                 "<dl>\n"
 175                 + "<dt><span class=\"paramLabel\">Parameters:</span></dt>\n"
 176                 + "<dd><code>title</code> - the title</dd>\n"
 177                 + "<dd><code>test</code> - boolean value"
 178                 + "</dd>\n"
 179                 + "<dt><span class=\"throwsLabel\">Throws:</span></dt>\n"
 180                 + "<dd><code>java.lang.IllegalArgumentException</code> - if the "
 181                 + "<code>owner</code>'s\n"
 182                 + "     <code>GraphicsConfiguration</code> is not from a screen "
 183                 + "device</dd>\n"
 184                 + "<dd><code>HeadlessException</code></dd>\n"
 185                 + "</dl>",
 186                 "<dl>\n"
 187                 + "<dt><span class=\"paramLabel\">Parameters:</span></dt>\n"
 188                 + "<dd><code>undecorated"
 189                 + "</code> - <code>true</code> if no decorations are\n"
 190                 + "         to be enabled;\n"
 191                 + "         <code>false</code> "
 192                 + "if decorations are to be enabled.</dd>\n"
 193                 + "<dt><span class=\"simpleTagLabel\">Since:"
 194                 + "</span></dt>\n"
 195                 + "<dd>1.4</dd>\n"
 196                 + "<dt><span class=\"seeLabel\">See Also:</span></dt>\n"
 197                 + "<dd>"
 198                 + "<a href=\"#readObject()\"><code>readObject()"
 199                 + "</code></a></dd>\n"
 200                 + "</dl>",
 201                 "<dl>\n"
 202                 + "<dt><span class=\"throwsLabel\">Throws:</span></dt>\n"
 203                 + "<dd><code>java.io.IOException</code></dd>\n"
 204                 + "<dt><span class=\"seeLabel\">See Also:"
 205                 + "</span></dt>\n"
 206                 + "<dd><a href=\"#setUndecorated(boolean)\">"
 207                 + "<code>setUndecorated(boolean)</code></a></dd>\n"
 208                 + "</dl>");
 209 
 210         checkOutput("pkg1/C2.html", expectFound,
 211                 "<dl>\n"
 212                 + "<dt><span class=\"paramLabel\">Parameters:"
 213                 + "</span></dt>\n"
 214                 + "<dd><code>set</code> - boolean</dd>\n"
 215                 + "<dt><span class=\"simpleTagLabel\">"
 216                 + "Since:</span></dt>\n"
 217                 + "<dd>1.4</dd>\n"
 218                 + "</dl>");
 219 
 220         checkOutput("serialized-form.html", expectFound,
 221                 "<dl>\n"
 222                 + "<dt><span class=\"throwsLabel\">Throws:</span>"
 223                 + "</dt>\n"
 224                 + "<dd><code>"
 225                 + "java.io.IOException</code></dd>\n"
 226                 + "<dt><span class=\"seeLabel\">See Also:</span>"
 227                 + "</dt>\n"
 228                 + "<dd><a href=\"pkg1/C1.html#setUndecorated(boolean)\">"
 229                 + "<code>C1.setUndecorated(boolean)</code></a></dd>\n"
 230                 + "</dl>",
 231                 "<span class=\"deprecatedLabel\">Deprecated.</span>\n"
 232                 + "<div class=\"deprecationComment\">As of JDK version 1.5, replaced by\n"
 233                 + " <a href=\"pkg1/C1.html#setUndecorated(boolean)\">"
 234                 + "<code>setUndecorated(boolean)</code></a>.</div>\n"
 235                 + "</div>\n"
 236                 + "<div class=\"block\">This field indicates whether the C1 is "
 237                 + "undecorated.</div>\n"
 238                 + "&nbsp;\n"
 239                 + "<dl>\n"
 240                 + "<dt><span class=\"simpleTagLabel\">Since:</span></dt>\n"
 241                 + "<dd>1.4</dd>\n"
 242                 + "<dt><span class=\"seeLabel\">See Also:</span>"
 243                 + "</dt>\n"
 244                 + "<dd><a href=\"pkg1/C1.html#setUndecorated(boolean)\">"
 245                 + "<code>C1.setUndecorated(boolean)</code></a></dd>\n"
 246                 + "</dl>",
 247                 "<span class=\"deprecatedLabel\">Deprecated.</span>\n"
 248                 + "<div class=\"deprecationComment\">As of JDK version 1.5, replaced by\n"
 249                 + " <a href=\"pkg1/C1.html#setUndecorated(boolean)\">"
 250                 + "<code>setUndecorated(boolean)</code></a>.</div>\n"
 251                 + "</div>\n"
 252                 + "<div class=\"block\">Reads the object stream.</div>\n"
 253                 + "<dl>\n"
 254                 + "<dt><span class=\"throwsLabel\">Throws:"
 255                 + "</span></dt>\n"
 256                 + "<dd><code>java.io.IOException</code></dd>\n"
 257                 + "</dl>",
 258                 "<span class=\"deprecatedLabel\">Deprecated.</span>"
 259                 + "</div>\n"
 260                 + "<div class=\"block\">The name for this class.</div>");
 261     }
 262 
 263     void checkNoDeprecated() {
 264         // Test with -nodeprecated option. The ClassDocs should have properly nested
 265         // definition list tags enclosing comments and tags. The ClassDocs should not
 266         // display definition list for deprecated information. The serialized form
 267         // should display properly nested definition list tags for comments, tags
 268         // and deprecated information.
 269         checkOutput("pkg1/package-summary.html", true,
 270                 "<dl>\n" +
 271                 "<dt><span class=\"simpleTagLabel\">Since:</span></dt>\n" +
 272                 "<dd>JDK1.0</dd>\n" +
 273                 "</dl>");
 274 
 275         checkOutput("pkg1/C1.html", true,
 276                 "<dl>\n" +
 277                 "<dt><span class=\"simpleTagLabel\">Since:</span>" +
 278                 "</dt>\n" +
 279                 "<dd>JDK1.0</dd>\n" +
 280                 "<dt><span class=\"seeLabel\">See Also:" +
 281                 "</span></dt>\n" +
 282                 "<dd><a href=\"C2.html\" title=\"class in pkg1\">" +
 283                 "<code>C2</code></a>, \n" +
 284                 "<a href=\"../serialized-form.html#pkg1.C1\">" +
 285                 "Serialized Form</a></dd>\n" +
 286                 "</dl>");
 287 
 288         checkOutput("pkg1/C1.html", true,
 289                 "<dl>\n"
 290                 + "<dt><span class=\"paramLabel\">Parameters:"
 291                 + "</span></dt>\n"
 292                 + "<dd><code>title</code> - the title</dd>\n"
 293                 + "<dd><code>"
 294                 + "test</code> - boolean value</dd>\n"
 295                 + "<dt><span class=\"throwsLabel\">Throws:"
 296                 + "</span></dt>\n"
 297                 + "<dd><code>java.lang.IllegalArgumentException"
 298                 + "</code> - if the <code>owner</code>'s\n"
 299                 + "     <code>GraphicsConfiguration"
 300                 + "</code> is not from a screen device</dd>\n"
 301                 + "<dd><code>"
 302                 + "HeadlessException</code></dd>\n"
 303                 + "</dl>",
 304                 "<dl>\n"
 305                 + "<dt><span class=\"paramLabel\">Parameters:"
 306                 + "</span></dt>\n"
 307                 + "<dd><code>undecorated</code> - <code>true</code>"
 308                 + " if no decorations are\n"
 309                 + "         to be enabled;\n"
 310                 + "         <code>false</code> if decorations are to be enabled."
 311                 + "</dd>\n"
 312                 + "<dt><span class=\"simpleTagLabel\">Since:</span></dt>\n"
 313                 + "<dd>1.4</dd>\n"
 314                 + "<dt><span class=\"seeLabel\">See Also:</span></dt>\n"
 315                 + "<dd><a href=\"#readObject()\">"
 316                 + "<code>readObject()</code></a></dd>\n"
 317                 + "</dl>",
 318                 "<dl>\n"
 319                 + "<dt><span class=\"throwsLabel\">Throws:</span>"
 320                 + "</dt>\n"
 321                 + "<dd><code>java.io.IOException</code></dd>\n"
 322                 + "<dt>"
 323                 + "<span class=\"seeLabel\">See Also:</span></dt>\n"
 324                 + "<dd><a href=\"#setUndecorated(boolean)\">"
 325                 + "<code>setUndecorated(boolean)</code></a></dd>\n"
 326                 + "</dl>");
 327 
 328         checkOutput("serialized-form.html", true,
 329                 "<dl>\n"
 330                 + "<dt><span class=\"throwsLabel\">Throws:</span>"
 331                 + "</dt>\n"
 332                 + "<dd><code>"
 333                 + "java.io.IOException</code></dd>\n"
 334                 + "<dt><span class=\"seeLabel\">See Also:</span>"
 335                 + "</dt>\n"
 336                 + "<dd><a href=\"pkg1/C1.html#setUndecorated(boolean)\">"
 337                 + "<code>C1.setUndecorated(boolean)</code></a></dd>\n"
 338                 + "</dl>",
 339                 "<span class=\"deprecatedLabel\">Deprecated.</span>\n"
 340                 + "<div class=\"deprecationComment\">As of JDK version 1.5, replaced by\n"
 341                 + " <a href=\"pkg1/C1.html#setUndecorated(boolean)\">"
 342                 + "<code>setUndecorated(boolean)</code></a>.</div>\n"
 343                 + "</div>\n"
 344                 + "<div class=\"block\">This field indicates whether the C1 is "
 345                 + "undecorated.</div>\n"
 346                 + "&nbsp;\n"
 347                 + "<dl>\n"
 348                 + "<dt><span class=\"simpleTagLabel\">Since:</span></dt>\n"
 349                 + "<dd>1.4</dd>\n"
 350                 + "<dt><span class=\"seeLabel\">See Also:</span>"
 351                 + "</dt>\n"
 352                 + "<dd><a href=\"pkg1/C1.html#setUndecorated(boolean)\">"
 353                 + "<code>C1.setUndecorated(boolean)</code></a></dd>\n"
 354                 + "</dl>",
 355                 "<span class=\"deprecatedLabel\">Deprecated.</span>\n"
 356                 + "<div class=\"deprecationComment\">As of JDK version 1.5, replaced by\n"
 357                 + " <a href=\"pkg1/C1.html#setUndecorated(boolean)\">"
 358                 + "<code>setUndecorated(boolean)</code></a>.</div>\n"
 359                 + "</div>\n"
 360                 + "<div class=\"block\">Reads the object stream.</div>\n"
 361                 + "<dl>\n"
 362                 + "<dt><span class=\"throwsLabel\">Throws:"
 363                 + "</span></dt>\n"
 364                 + "<dd><code>java.io.IOException</code></dd>\n"
 365                 + "</dl>",
 366                 "<span class=\"deprecatedLabel\">Deprecated.</span>"
 367                 + "</div>\n"
 368                 + "<div class=\"block\">"
 369                 + "The name for this class.</div>");
 370     }
 371 
 372     void checkNoCommentNoDeprecated(boolean expectFound) {
 373         // Test with -nocomment and -nodeprecated options. The ClassDocs whould
 374         // not display definition lists for any member details.
 375         checkOutput("pkg1/C1.html", expectFound,
 376                 "<pre class=\"methodSignature\">public&nbsp;void&nbsp;readObject()\n" +
 377                 "                throws java.io.IOException</pre>\n" +
 378                 "</li>");
 379 
 380         checkOutput("pkg1/C2.html", expectFound,
 381                 "<pre>public&nbsp;C2()</pre>\n" +
 382                 "</li>");
 383 
 384         checkOutput("pkg1/C1.ModalExclusionType.html", expectFound,
 385                 "<pre>public " +
 386                 "static final&nbsp;<a href=\"C1.ModalExclusionType.html\" " +
 387                 "title=\"enum in pkg1\">C1.ModalExclusionType</a> " +
 388                 "APPLICATION_EXCLUDE</pre>\n" +
 389                 "</li>");
 390 
 391         checkOutput("serialized-form.html", expectFound,
 392                 "<pre>boolean " +
 393                 "undecorated</pre>\n" +
 394                 "<div class=\"deprecationBlock\"><span class=\"deprecatedLabel\">" +
 395                 "Deprecated.</span>\n"
 396                 + "<div class=\"deprecationComment\">As of JDK version 1.5, replaced by\n"
 397                 + " <a href=\"pkg1/C1.html#setUndecorated(boolean)\"><code>"
 398                 + "setUndecorated(boolean)</code></a>.</div>\n"
 399                 + "</div>\n"
 400                 +
 401                 "</li>",
 402                 "<span class=\"deprecatedLabel\">"
 403                 + "Deprecated.</span>\n"
 404                 + "<div class=\"deprecationComment\">As of JDK version"
 405                 + " 1.5, replaced by\n"
 406                 + " <a href=\"pkg1/C1.html#setUndecorated(boolean)\">"
 407                 + "<code>setUndecorated(boolean)</code></a>.</div>\n"
 408                 + "</div>\n"
 409                 + "</li>");
 410     }
 411 }
--- EOF ---