0a58cffe88
8329296: Update Elements for '///' documentation comments Co-authored-by: Jim Laskey <jlaskey@openjdk.org> Reviewed-by: prappo, darcy, hannesw
275 lines
11 KiB
Java
275 lines
11 KiB
Java
/*
|
|
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
|
|
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
*
|
|
* This code is free software; you can redistribute it and/or modify it
|
|
* under the terms of the GNU General Public License version 2 only, as
|
|
* published by the Free Software Foundation.
|
|
*
|
|
* This code is distributed in the hope that it will be useful, but WITHOUT
|
|
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
* version 2 for more details (a copy is included in the LICENSE file that
|
|
* accompanied this code).
|
|
*
|
|
* You should have received a copy of the GNU General Public License version
|
|
* 2 along with this work; if not, write to the Free Software Foundation,
|
|
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
*
|
|
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
|
* or visit www.oracle.com if you need additional information or have any
|
|
* questions.
|
|
*/
|
|
|
|
/*
|
|
* @test
|
|
* @bug 8298405
|
|
* @summary Markdown support in the standard doclet
|
|
* @library /tools/lib ../../lib
|
|
* @modules jdk.javadoc/jdk.javadoc.internal.tool
|
|
* @build toolbox.ToolBox javadoc.tester.*
|
|
* @run main TestMarkdownFirstSentence
|
|
*/
|
|
|
|
import javadoc.tester.JavadocTester;
|
|
import toolbox.ToolBox;
|
|
|
|
import java.nio.file.Path;
|
|
import java.util.List;
|
|
|
|
public class TestMarkdownFirstSentence extends JavadocTester {
|
|
|
|
public static void main(String... args) throws Exception {
|
|
var tester = new TestMarkdownFirstSentence();
|
|
tester.runTests();
|
|
}
|
|
|
|
ToolBox tb = new ToolBox();
|
|
|
|
@Test
|
|
public void testFirstSentence(Path base) throws Exception {
|
|
Path src = base.resolve("src");
|
|
tb.writeJavaFiles(src,
|
|
"""
|
|
package p;
|
|
public class C {
|
|
/// This is the _first_ sentence.
|
|
/// This is the _second_ sentence.
|
|
public void m() { }
|
|
}
|
|
""");
|
|
javadoc("-d", base.resolve("api").toString(),
|
|
"-Xdoclint:none",
|
|
"--source-path", src.toString(),
|
|
"p");
|
|
|
|
checkOrder("p/C.html",
|
|
"""
|
|
<section class="method-summary" id="method-summary">""",
|
|
"""
|
|
<div class="block">This is the <em>first</em> sentence.</div>""",
|
|
"""
|
|
<section class="method-details" id="method-detail">""",
|
|
"""
|
|
<div class="block">This is the <em>first</em> sentence.
|
|
This is the <em>second</em> sentence.</div>""");
|
|
}
|
|
|
|
// Test the ability to put links in the first sentence of a description.
|
|
// Note that user-defined reference links cannot be used in the first
|
|
// sentence, and so in that case we verify the behavior is "as expected".
|
|
@Test
|
|
public void testFirstSentenceLinks(Path base) throws Exception {
|
|
Path src = base.resolve("src");
|
|
|
|
// Apart from the (control) case, the other cases exercise
|
|
// various kinds of links in the first sentence of a description.
|
|
// Note the last case is an explicit test of a link that is
|
|
// _not_ currently supported, since the link reference definition
|
|
// is not part of the first sentence.
|
|
tb.writeJavaFiles(src,
|
|
"""
|
|
package p;
|
|
import q.MyObject;
|
|
public class C {
|
|
/// First sentence.
|
|
/// Control: [MyObject]
|
|
public void m1() { }
|
|
|
|
/// Simple autoref in first sentence [MyObject].
|
|
/// More.
|
|
public void m2() { }
|
|
|
|
/// Qualified autoref in first sentence [q.MyObject].
|
|
/// More.
|
|
public void m3() { }
|
|
|
|
/// Standard link with periods [example.com](http://example.com).
|
|
/// More.
|
|
public void m4() { }
|
|
|
|
/// Manual ref link [foo].
|
|
/// More.
|
|
///
|
|
/// [foo]: http:example.com
|
|
public void m5() { }
|
|
}""",
|
|
// use a simple class in a different package, to avoid platform links to system classes
|
|
"""
|
|
package q;
|
|
public class MyObject { }""");
|
|
|
|
javadoc("-d", base.resolve("api").toString(),
|
|
"-Xdoclint:none",
|
|
"--source-path", src.toString(),
|
|
"p", "q");
|
|
checkExit(Exit.OK);
|
|
|
|
// use checkOrder and the delimiter comments to ensure that
|
|
// we check the strings in the method summary table, and not
|
|
// subsequently in the method details section.
|
|
checkOrder("p/C.html",
|
|
"<!-- ========== METHOD SUMMARY =========== -->",
|
|
"""
|
|
<div class="block">Simple autoref in first sentence <a href="../q/MyObject.html" \
|
|
title="class in q"><code>MyObject</code></a>.</div>""",
|
|
"""
|
|
<div class="block">Qualified autoref in first sentence <a href="../q/MyObject.html" \
|
|
title="class in q"><code>MyObject</code></a>.</div>""",
|
|
"""
|
|
<div class="block">Standard link with periods \
|
|
<a href="http://example.com">example.com</a>.</div>""",
|
|
// The following is a test of the regrettably expected behavior,
|
|
// because the link reference definition is not carried into
|
|
// the first sentence.
|
|
"""
|
|
<div class="block">Manual ref link [foo].</div>""",
|
|
"<!-- ============ METHOD DETAIL ========== -->"
|
|
);
|
|
}
|
|
|
|
// Test that periods within certain constructs do not prematurely terminate
|
|
// the first sentence.
|
|
@Test
|
|
public void testFirstSentencePeriods(Path base) throws Exception {
|
|
testFirstSentencePeriods(base.resolve("no-bi"), false);
|
|
testFirstSentencePeriods(base.resolve("bi"), true);
|
|
}
|
|
|
|
void testFirstSentencePeriods(Path base, boolean useBreakIterator) throws Exception {
|
|
Path src = base.resolve("src");
|
|
|
|
tb.writeJavaFiles(src,
|
|
"""
|
|
package p;
|
|
public class C {
|
|
/// Code span `1.0` end.
|
|
/// More.
|
|
public void m1() { }
|
|
/// Complex code span ``` `1.0` ``` end.
|
|
/// More.
|
|
public void m2() { }
|
|
/// Period space `1. 2. 3.` end.
|
|
/// More.
|
|
public void m3() { }
|
|
/// Link [example.com](http://example.com) end.
|
|
/// More.
|
|
public void m4() { }
|
|
}
|
|
""");
|
|
|
|
javadoc("-d", base.resolve("api").toString(),
|
|
"-Xdoclint:none",
|
|
(useBreakIterator ? "-breakiterator" : "-XDdummy"),
|
|
"--source-path", src.toString(),
|
|
"p");
|
|
checkExit(Exit.OK);
|
|
|
|
// use checkOrder and the delimiter comments to ensure that
|
|
// we check the strings in the method summary table, and not
|
|
// subsequently in the method details section.
|
|
checkOrder("p/C.html",
|
|
"<!-- ========== METHOD SUMMARY =========== -->",
|
|
"""
|
|
<div class="block">Code span <code>1.0</code> end.</div>""",
|
|
"""
|
|
<div class="block">Complex code span <code>`1.0`</code> end.</div>""",
|
|
"""
|
|
<div class="block">Period space <code>1. 2. 3.</code> end.</div>""",
|
|
"""
|
|
<div class="block">Link <a href="http://example.com">example.com</a> end.</div>""",
|
|
"<!-- ============ METHOD DETAIL ========== -->"
|
|
);
|
|
}
|
|
|
|
@Test
|
|
public void testIndentedInlineReturn(Path base) throws Exception {
|
|
//this is a Markdown-specific test, because leading whitespace is ignored in HTML comments
|
|
Path src = base.resolve("src");
|
|
tb.writeJavaFiles(src,
|
|
"""
|
|
package p;
|
|
/// Class description.
|
|
public class C {
|
|
/// {@return an int}
|
|
/// More description.
|
|
public int m() { return 0; }
|
|
}
|
|
""");
|
|
javadoc("-d", base.resolve("api").toString(),
|
|
"--source-path", src.toString(),
|
|
"p");
|
|
|
|
checkOutput("p/C.html", true,
|
|
"""
|
|
<section class="detail" id="m()">
|
|
<h3>m</h3>
|
|
<div class="horizontal-scroll">
|
|
<div class="member-signature"><span class="modifiers">public</span> <span class="return-type">int</span> <span class="element-name">m</span>()</div>
|
|
<div class="block">Returns an int.
|
|
More description.</div>
|
|
<dl class="notes">
|
|
<dt>Returns:</dt>
|
|
<dd>an int</dd>
|
|
</dl>
|
|
</div>
|
|
</section>""");
|
|
}
|
|
|
|
@Test
|
|
public void testExtraPara(Path base) throws Exception {
|
|
Path src = base.resolve("src");
|
|
tb.writeJavaFiles(src,
|
|
"""
|
|
package p;
|
|
/// This is the class description.
|
|
///
|
|
/// # Heading
|
|
/// Lorem ipsum
|
|
public class C { }
|
|
""");
|
|
javadoc("-d", base.resolve("api").toString(),
|
|
"--no-platform-links",
|
|
"--source-path", src.toString(),
|
|
"p");
|
|
|
|
checkOutput("p/package-summary.html", true,
|
|
"""
|
|
<div class="col-first even-row-color class-summary class-summary-tab2"><a href="C.html" title="clas\
|
|
s in p">C</a></div>
|
|
<div class="col-last even-row-color class-summary class-summary-tab2">
|
|
<div class="block">This is the class description.</div>
|
|
</div>""");
|
|
|
|
checkOutput("p/C.html", true,
|
|
"""
|
|
<span class="element-name type-name-label">C</span>
|
|
<span class="extends-implements">extends java.lang.Object</span></div>
|
|
<div class="block"><p>This is the class description.</p>
|
|
<h2 id="heading-heading">Heading</h2>
|
|
<p>Lorem ipsum</p>
|
|
</div>""");
|
|
|
|
}
|
|
}
|