1 /*
   2  * Copyright (c) 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      8225055
  27  * @summary  Record types
  28  * @library  /tools/lib ../../lib
  29  * @modules jdk.javadoc/jdk.javadoc.internal.tool
  30  * @build    toolbox.ToolBox javadoc.tester.*
  31  * @run main TestRecordTypes
  32  */
  33 
  34 
  35 import java.io.IOException;
  36 import java.nio.file.Path;
  37 
  38 import javadoc.tester.JavadocTester;
  39 import toolbox.ToolBox;
  40 
  41 public class TestRecordTypes extends JavadocTester {
  42 
  43     public static void main(String... args) throws Exception {
  44         TestRecordTypes tester = new TestRecordTypes();
  45         tester.runTests(m -> new Object[] { Path.of(m.getName()) });
  46     }
  47 
  48     private final ToolBox tb = new ToolBox();
  49 
  50     @Test
  51     public void testRecordKeywordUnnamedPackage(Path base) throws IOException {
  52         Path src = base.resolve("src");
  53         tb.writeJavaFiles(src,
  54                 "public record R(int r1) { }");
  55 
  56         javadoc("-d", base.resolve("out").toString(),
  57                 "-sourcepath", src.toString(),
  58                 src.resolve("R.java").toString());
  59         checkExit(Exit.OK);
  60 
  61         checkOutput("R.html", true,
  62                 "<h1 title=\"Record R\" class=\"title\">Record R</h1>",
  63                 "public record <span class=\"typeNameLabel\">R</span>",
  64                 "<code><span class=\"memberNameLink\"><a href=\"#%3Cinit%3E(int)\">R</a></span>​(int&nbsp;r1)</code>");
  65     }
  66 
  67     @Test
  68     public void testRecordKeywordNamedPackage(Path base) throws IOException {
  69         Path src = base.resolve("src");
  70         tb.writeJavaFiles(src,
  71                 "package p; public record R(int r1) { }");
  72 
  73         javadoc("-d", base.resolve("out").toString(),
  74                 "-sourcepath", src.toString(),
  75                 "p");
  76         checkExit(Exit.OK);
  77 
  78         checkOutput("p/R.html", true,
  79                 "<h1 title=\"Record R\" class=\"title\">Record R</h1>",
  80                 "public record <span class=\"typeNameLabel\">R</span>",
  81                 "<code><span class=\"memberNameLink\"><a href=\"#%3Cinit%3E(int)\">R</a></span>​(int&nbsp;r1)</code>");
  82     }
  83 
  84     @Test
  85     public void testEmptyRecord(Path base) throws IOException {
  86         Path src = base.resolve("src");
  87         tb.writeJavaFiles(src,
  88                 "package p; public record R() { }");
  89 
  90         javadoc("-d", base.resolve("out").toString(),
  91                 "-sourcepath", src.toString(),
  92                 "p");
  93         checkExit(Exit.OK);
  94 
  95         checkOutput("p/R.html", true,
  96                 "<h1 title=\"Record R\" class=\"title\">Record R</h1>",
  97                 "public record <span class=\"typeNameLabel\">R</span>",
  98                 "<code><span class=\"memberNameLink\"><a href=\"#%3Cinit%3E()\">R</a></span>()</code>");
  99     }
 100 
 101     @Test
 102     public void testAtParam(Path base) throws IOException {
 103         Path src = base.resolve("src");
 104         tb.writeJavaFiles(src,
 105                 "package p; /** This is record R. \n"
 106                 + " * @param r1 This is a component.\n"
 107                 + " */\n"
 108                 + "public record R(int r1) { }");
 109 
 110         javadoc("-d", base.resolve("out").toString(),
 111                 "-sourcepath", src.toString(),
 112                 "p");
 113         checkExit(Exit.OK);
 114 
 115         checkOutput("p/R.html", true,
 116                 "<h1 title=\"Record R\" class=\"title\">Record R</h1>",
 117                 "public record <span class=\"typeNameLabel\">R</span>",
 118                 "<dl>\n"
 119                 + "<dt><span class=\"paramLabel\">State Components:</span></dt>\n"
 120                 + "<dd><code><a id=\"param-r1\">r1</a></code> - This is a component.</dd>\n"
 121                 + "</dl>",
 122                 "<code><span class=\"memberNameLink\"><a href=\"#%3Cinit%3E(int)\">R</a></span>​(int&nbsp;r1)</code>");
 123     }
 124 
 125     @Test
 126     public void testAtParamTyParam(Path base) throws IOException {
 127         Path src = base.resolve("src");
 128         tb.writeJavaFiles(src,
 129                 "package p; /** This is record R. \n"
 130                 + " * @param r1  This is a component.\n"
 131                 + " * @param <T> This is a type parameter.\n"
 132                 + " */\n"
 133                 + "public record R<T>(int r1) { }");
 134 
 135         javadoc("-d", base.resolve("out").toString(),
 136                 "-sourcepath", src.toString(),
 137                 "p");
 138         checkExit(Exit.OK);
 139 
 140         checkOutput("p/R.html", true,
 141                 "<h1 title=\"Record R\" class=\"title\">Record R&lt;T&gt;</h1>",
 142                 "public record <span class=\"typeNameLabel\">R&lt;T&gt;</span>",
 143                 "<dl>\n"
 144                 + "<dt><span class=\"paramLabel\">Type Parameters:</span></dt>\n"
 145                 + "<dd><code>T</code> - This is a type parameter.</dd>\n"
 146                 + "<dt><span class=\"paramLabel\">State Components:</span></dt>\n"
 147                 + "<dd><code><a id=\"param-r1\">r1</a></code> - This is a component.</dd>\n"
 148                 + "</dl>",
 149                 "<code><span class=\"memberNameLink\"><a href=\"#%3Cinit%3E(int)\">R</a></span>​(int&nbsp;r1)</code>");
 150     }
 151 
 152     @Test
 153     public void testGeneratedComments(Path base) throws IOException {
 154         Path src = base.resolve("src");
 155         tb.writeJavaFiles(src,
 156                 "package p; /** This is record R. \n"
 157                         + " * @param r1  This is a component.\n"
 158                         + " */\n"
 159                         + "public record R(int r1) { }");
 160 
 161         javadoc("-d", base.resolve("out").toString(),
 162                 "-sourcepath", src.toString(),
 163                 "p");
 164         checkExit(Exit.OK);
 165 
 166         // While we don't normally test values that just come from resource files,
 167         // in these cases, we want to verify that something non-empty was put into
 168         // the documentation for the generated members.
 169         checkOrder("p/R.html",
 170                 "<section class=\"constructorSummary\">",
 171                 "<a href=\"#%3Cinit%3E(int)\">R</a>",
 172                 "Creates an instance of a <code>R</code> record.",
 173                 "<section class=\"methodSummary\">",
 174                 "<a href=\"#equals(java.lang.Object)\">equals</a>",
 175                 "Indicates whether some other object is \"equal to\" this one.",
 176                 "<a href=\"#hashCode()\">hashCode</a>",
 177                 "Returns a hash code value for this object.",
 178                 "<a href=\"#r1()\">r1</a>",
 179                 "Returns the value of the <a href=\"#param-r1\"><code>r1</code></a> state component.",
 180                 "<a href=\"#toString()\">toString</a>",
 181                 "Returns a string representation of this object."
 182         );
 183     }
 184 
 185     @Test
 186     public void testUserComments(Path base) throws IOException {
 187         Path src = base.resolve("src");
 188         tb.writeJavaFiles(src,
 189                 "package p; /** This is record R. \n"
 190                 + " * @param r1  This is a component.\n"
 191                 + " */\n"
 192                 + "public record R(int r1) {\n"
 193                 + "/** User constructor. */ public R { }\n"
 194                 + "/** User equals. */ public boolean equals(Object other) { return false; }\n"
 195                 + "/** User hashCode. */ public int hashCode() { return 0; }\n"
 196                 + "/** User toString. */ public String toString() { return \"\"; }\n"
 197                 + "/** User accessor. */ public int r1() { return r1; }\n"
 198                 + "}");
 199 
 200         javadoc("-d", base.resolve("out").toString(),
 201                 "-sourcepath", src.toString(),
 202                 "p");
 203         checkExit(Exit.OK);
 204 
 205         checkOrder("p/R.html",
 206                 "<section class=\"constructorSummary\">",
 207                 "<a href=\"#%3Cinit%3E(int)\">R</a>",
 208                 "User constructor.",
 209                 "<section class=\"methodSummary\">",
 210                 "<a href=\"#equals(java.lang.Object)\">equals</a>",
 211                 "User equals.",
 212                 "<a href=\"#hashCode()\">hashCode</a>",
 213                 "User hashCode.",
 214                 "<a href=\"#r1()\">r1</a>",
 215                 "User accessor.",
 216                 "<a href=\"#toString()\">toString</a>",
 217                 "User toString."
 218         );
 219     }
 220 
 221 }