From 2ad2cce6e0e768bdf0df33d2bfa88f62568b406a Mon Sep 17 00:00:00 2001 From: Jonathan Gibbons Date: Mon, 20 May 2019 10:57:57 -0700 Subject: [PATCH] 8223663: Update links for tool guides Reviewed-by: alanb, erikj, darcy --- make/Docs.gmk | 1 + .../classes/build/tools/taglet/ToolGuide.java | 159 ++++++++++++++++++ src/java.base/share/classes/module-info.java | 6 +- src/java.rmi/share/classes/module-info.java | 10 +- .../share/classes/module-info.java | 7 +- .../share/classes/module-info.java | 7 +- .../share/classes/module-info.java | 7 +- .../share/classes/module-info.java | 9 +- .../share/classes/module-info.java | 7 +- src/jdk.jcmd/share/classes/module-info.java | 18 +- .../share/classes/module-info.java | 9 +- src/jdk.jdeps/share/classes/module-info.java | 11 +- src/jdk.jdi/share/classes/module-info.java | 7 +- src/jdk.jfr/share/classes/module-info.java | 7 +- src/jdk.jlink/share/classes/module-info.java | 12 +- src/jdk.jshell/share/classes/module-info.java | 5 +- src/jdk.jstatd/share/classes/module-info.java | 7 +- src/jdk.pack/share/classes/module-info.java | 9 +- src/jdk.rmic/share/classes/module-info.java | 7 +- .../share/classes/module-info.java | 7 +- 20 files changed, 210 insertions(+), 102 deletions(-) create mode 100644 make/jdk/src/classes/build/tools/taglet/ToolGuide.java diff --git a/make/Docs.gmk b/make/Docs.gmk index 3668a602aa4..497edcaee77 100644 --- a/make/Docs.gmk +++ b/make/Docs.gmk @@ -86,6 +86,7 @@ JAVADOC_TAGS := \ -tag return \ -tag throws \ -taglet build.tools.taglet.ModuleGraph \ + -taglet build.tools.taglet.ToolGuide \ -tag since \ -tag serialData \ -tag factory \ diff --git a/make/jdk/src/classes/build/tools/taglet/ToolGuide.java b/make/jdk/src/classes/build/tools/taglet/ToolGuide.java new file mode 100644 index 00000000000..b6e57275a00 --- /dev/null +++ b/make/jdk/src/classes/build/tools/taglet/ToolGuide.java @@ -0,0 +1,159 @@ +/* + * Copyright (c) 2017, 2019, 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. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * 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. + */ + +package build.tools.taglet; + +import java.util.EnumSet; +import java.util.List; +import java.util.Set; +import java.util.regex.Matcher; +import java.util.regex.Pattern; +import javax.lang.model.element.Element; +import javax.lang.model.element.ModuleElement; +import javax.lang.model.element.PackageElement; + +import com.sun.source.doctree.DocTree; +import com.sun.source.doctree.UnknownBlockTagTree; +import jdk.javadoc.doclet.Taglet; + +import static com.sun.source.doctree.DocTree.Kind.*; +import static jdk.javadoc.doclet.Taglet.Location.*; + +/** + * A block tag to insert a link to tool guide in a nearby directory. + * The tag can be used as follows: + * + * + * If the label is omitted, it defaults to the tool name. + * + * For example + *

+ * @toolGuide javac + *

+ * will produce the following html, depending on the file containing + * the tag. + *

+ * {@code + *

Tool Guides: + *
javac + * } + */ +public class ToolGuide implements Taglet { + + static final String TAG_NAME = "toolGuide"; + + static final String BASE_URL = "../specs/man"; + + static final Pattern TAG_PATTERN = Pattern.compile("(?s)(?[A-Za-z0-9]+)\\s*(?
Tool Guides:
\n") + .append("
"); + + boolean needComma = false; + for (DocTree tag : tags) { + + if (tag.getKind() != UNKNOWN_BLOCK_TAG) { + continue; + } + + UnknownBlockTagTree blockTag = (UnknownBlockTagTree)tag; + String tagText = blockTag.getContent().toString().trim(); + Matcher m = TAG_PATTERN.matcher(tagText); + if (m.matches()) { + String name = m.group("name"); + String label = m.group("label"); + if (label.isEmpty()) { + label = name; + } + + String url = String.format("%s/%s/%s.html", + docRoot(elem), BASE_URL, name); + + if (needComma) { + sb.append(",\n"); + } else { + needComma = true; + } + + sb.append("") + .append(label) + .append(""); + } + } + + sb.append("
\n"); + + return sb.toString(); + } + + private String docRoot(Element elem) { + switch (elem.getKind()) { + case MODULE: + return ".."; + + case PACKAGE: + PackageElement pe = (PackageElement)elem; + String pkgPart = pe.getQualifiedName() + .toString() + .replace('.', '/') + .replaceAll("[^/]+", ".."); + return pe.getEnclosingElement() != null + ? "../" + pkgPart + : pkgPart; + + default: + throw new IllegalArgumentException(elem.getKind().toString()); + } + } +} diff --git a/src/java.base/share/classes/module-info.java b/src/java.base/share/classes/module-info.java index f53243d6b1e..b9ea6e59740 100644 --- a/src/java.base/share/classes/module-info.java +++ b/src/java.base/share/classes/module-info.java @@ -36,11 +36,11 @@ * {@link java.nio.file.FileSystems#newFileSystem * FileSystems.newFileSystem(URI.create("jrt:/"))}. * - *
Tool Guides:
- *
{@extLink java_tool_reference java launcher}, - * {@extLink keytool_tool_reference keytool}
* * + * @toolGuide java java launcher + * @toolGuide keytool + * * @provides java.nio.file.spi.FileSystemProvider * * @uses java.lang.System.LoggerFinder diff --git a/src/java.rmi/share/classes/module-info.java b/src/java.rmi/share/classes/module-info.java index cbf31a0f069..5c2aad1255b 100644 --- a/src/java.rmi/share/classes/module-info.java +++ b/src/java.rmi/share/classes/module-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2014, 2019, 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 @@ -31,12 +31,8 @@ * object registry, and the {@index rmid rmid tool} tool to start * the activation system daemon. * - *
- *
Tool Guides:
- *
{@extLink rmiregistry_tool_reference rmiregistry}, - * {@extLink rmid_tool_reference rmid} - *
- *
+ * @toolGuide rmiregistry + * @toolGuide rmid * * @uses java.rmi.server.RMIClassLoaderSpi * diff --git a/src/java.scripting/share/classes/module-info.java b/src/java.scripting/share/classes/module-info.java index f2d8173d74b..4367a55a5a1 100644 --- a/src/java.scripting/share/classes/module-info.java +++ b/src/java.scripting/share/classes/module-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2014, 2019, 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 @@ -31,10 +31,7 @@ * that supports executing JavaScript and other languages if its corresponding * script engine is installed. * - *
- *
Tool Guides: - *
{@extLink jrunscript_tool_reference jrunscript}
- *
+ * @toolGuide jrunscript * * @uses javax.script.ScriptEngineFactory * diff --git a/src/jdk.compiler/share/classes/module-info.java b/src/jdk.compiler/share/classes/module-info.java index aa611c789a3..da39bc61a19 100644 --- a/src/jdk.compiler/share/classes/module-info.java +++ b/src/jdk.compiler/share/classes/module-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014, 2018, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2014, 2019, 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 @@ -55,10 +55,7 @@ * {@code jdk.zipfs} module, must be available if the compiler is to be able * to read JAR files. * - *
- *
Tool Guides: - *
{@extLink javac_tool_reference javac} - *
+ * @toolGuide javac * * @provides java.util.spi.ToolProvider * @provides com.sun.tools.javac.platform.PlatformProvider diff --git a/src/jdk.hotspot.agent/share/classes/module-info.java b/src/jdk.hotspot.agent/share/classes/module-info.java index 2c9f4f26da5..8015105d8df 100644 --- a/src/jdk.hotspot.agent/share/classes/module-info.java +++ b/src/jdk.hotspot.agent/share/classes/module-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2014, 2019, 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 @@ -30,10 +30,7 @@ * attach to a running Java Virtual Machine (JVM) or launch a postmortem * debugger to analyze the content of a core-dump from a crashed JVM. * - *
- *
Tool Guides:
- *
{@extLink jhsdb_tool_reference jhsdb}
- *
+ * @toolGuide jhsdb * * @moduleGraph * @since 9 diff --git a/src/jdk.jartool/share/classes/module-info.java b/src/jdk.jartool/share/classes/module-info.java index f063d736ce4..1bba6faebaf 100644 --- a/src/jdk.jartool/share/classes/module-info.java +++ b/src/jdk.jartool/share/classes/module-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2014, 2019, 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 @@ -36,11 +36,8 @@ * or the {@linkplain java.util.ServiceLoader service loader} with the name * {@code "jar"}. * - *
- *
Tool Guides: - *
{@extLink jar_tool_reference jar}, - * {@extLink jarsigner_tool_reference jarsigner} - *
+ * @toolGuide jar + * @toolGuide jarsigner * * @moduleGraph * @since 9 diff --git a/src/jdk.javadoc/share/classes/module-info.java b/src/jdk.javadoc/share/classes/module-info.java index 635ab9e91f3..3da81c61c1f 100644 --- a/src/jdk.javadoc/share/classes/module-info.java +++ b/src/jdk.javadoc/share/classes/module-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014, 2018, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2014, 2019, 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 @@ -42,10 +42,7 @@ * or the {@linkplain java.util.ServiceLoader service loader} with the name * {@code "javadoc"}. * - *
- *
Tool Guides: - *
{@extLink javadoc_tool_reference javadoc} - *
+ * @toolGuide javadoc * * @provides java.util.spi.ToolProvider * @provides javax.tools.DocumentationTool diff --git a/src/jdk.jcmd/share/classes/module-info.java b/src/jdk.jcmd/share/classes/module-info.java index 9a5df56cdb5..a26565b5396 100644 --- a/src/jdk.jcmd/share/classes/module-info.java +++ b/src/jdk.jcmd/share/classes/module-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2014, 2019, 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 @@ -28,16 +28,12 @@ * such as the {@index jcmd jcmd tool}, {@index jps jps tool}, * {@index jstat jstat tool} tools. * - *
- *
Tool Guides: - *
- * {@extLink jcmd_tool_reference jcmd}, - * {@extLink jinfo_tool_reference jinfo}, - * {@extLink jmap_tool_reference jmap}, - * {@extLink jps_tool_reference jps}, - * {@extLink jstack_tool_reference jstack}, - * {@extLink jstat_tool_reference jstat} - *
+ * @toolGuide jcmd + * @toolGuide jinfo + * @toolGuide jmap + * @toolGuide jps + * @toolGuide jstack + * @toolGuide jstat * * @moduleGraph * @since 9 diff --git a/src/jdk.jconsole/share/classes/module-info.java b/src/jdk.jconsole/share/classes/module-info.java index 1db2244be34..bac908afa41 100644 --- a/src/jdk.jconsole/share/classes/module-info.java +++ b/src/jdk.jconsole/share/classes/module-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2014, 2019, 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 @@ -28,11 +28,12 @@ * for monitoring and managing a running application. * *
- *
Tool Guides: - *
{@extLink jconsole_tool_reference jconsole}, - * {@extLink using_jconsole Using JConsole} + *
See Also: + *
{@extLink using_jconsole Using JConsole} *
* + * @toolGuide jconsole + * * @uses com.sun.tools.jconsole.JConsolePlugin * * @moduleGraph diff --git a/src/jdk.jdeps/share/classes/module-info.java b/src/jdk.jdeps/share/classes/module-info.java index 0a061df8211..6bbfccc9c59 100644 --- a/src/jdk.jdeps/share/classes/module-info.java +++ b/src/jdk.jdeps/share/classes/module-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2015, 2019, 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 @@ -44,12 +44,9 @@ * jdeprscan only exists as a command line tool, and does not provide * any direct API. * - *
- *
Tool Guides: - *
{@extLink javap_tool_reference javap}, - * {@extLink jdeprscan_tool_reference jdeprscan}, - * {@extLink jdeps_tool_reference jdeps} - *
+ * @toolGuide javap + * @toolGuide jdeprscan + * @toolGuide jdeps * * @provides java.util.spi.ToolProvider * diff --git a/src/jdk.jdi/share/classes/module-info.java b/src/jdk.jdi/share/classes/module-info.java index 0ac3c64b672..98003d19712 100644 --- a/src/jdk.jdi/share/classes/module-info.java +++ b/src/jdk.jdi/share/classes/module-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2014, 2019, 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 @@ -104,10 +104,7 @@ * * * - *
- *
Tool Guides: - *
{@extLink jdb_tool_reference jdb} - *
+ * @toolGuide jdb * * @provides com.sun.jdi.connect.Connector * diff --git a/src/jdk.jfr/share/classes/module-info.java b/src/jdk.jfr/share/classes/module-info.java index dc65de9eb3b..702cc14a2f1 100644 --- a/src/jdk.jfr/share/classes/module-info.java +++ b/src/jdk.jfr/share/classes/module-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014, 2018, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2014, 2019, 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 @@ -27,11 +27,6 @@ * Defines the API for JDK Flight Recorder. *

* - *

- *
Tool Guides: - *
{@extLink jfr_tool_reference jfr} - *
- * * @moduleGraph * @since 9 */ diff --git a/src/jdk.jlink/share/classes/module-info.java b/src/jdk.jlink/share/classes/module-info.java index bbb0b785037..f3dc94b3fa6 100644 --- a/src/jdk.jlink/share/classes/module-info.java +++ b/src/jdk.jlink/share/classes/module-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2015, 2019, 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 @@ -30,8 +30,7 @@ * the JDK implementation-specific container file for classes and resources. * *

This module provides the equivalent of command-line access to the - * {@extLink jlink_tool_reference jlink} and - * {@extLink jmod_tool_reference jmod} tools via the + * jlink and jmod tools via the * {@link java.util.spi.ToolProvider ToolProvider} SPI. * Instances of the tools can be obtained by calling * {@link java.util.spi.ToolProvider#findFirst ToolProvider.findFirst} @@ -41,11 +40,8 @@ *

jimage only exists * as a command-line tool, and does not provide any direct API. * - *

- *
Tool Guides: - *
{@extLink jlink_tool_reference jlink}, - * {@extLink jmod_tool_reference jmod} - *
+ * @toolGuide jlink + * @toolGuide jmod * * @provides java.util.spi.ToolProvider * diff --git a/src/jdk.jshell/share/classes/module-info.java b/src/jdk.jshell/share/classes/module-info.java index 6b0ca1f558a..3f70ef55dbc 100644 --- a/src/jdk.jshell/share/classes/module-info.java +++ b/src/jdk.jshell/share/classes/module-info.java @@ -54,10 +54,7 @@ * definitions. *

* - *
- *
Tool Guides: - *
{@extLink jshell_tool_reference jshell} - *
+ * @toolGuide jshell * * @provides javax.tools.Tool * @provides jdk.jshell.spi.ExecutionControlProvider diff --git a/src/jdk.jstatd/share/classes/module-info.java b/src/jdk.jstatd/share/classes/module-info.java index dd3765a78c4..ade59da4248 100644 --- a/src/jdk.jstatd/share/classes/module-info.java +++ b/src/jdk.jstatd/share/classes/module-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2015, 2019, 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 @@ -27,10 +27,7 @@ * Defines the {@index jstatd jstatd tool} tool for starting a daemon * for the jstat tool to monitor JVM statistics remotely. * - *
- *
Tool Guides: - *
{@extLink jstatd_tool_reference jstatd} - *
+ * @toolGuide jstatd * * @moduleGraph * @since 9 diff --git a/src/jdk.pack/share/classes/module-info.java b/src/jdk.pack/share/classes/module-info.java index 4f5994b9567..d4952a50dec 100644 --- a/src/jdk.pack/share/classes/module-info.java +++ b/src/jdk.pack/share/classes/module-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2014, 2019, 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 @@ -29,11 +29,8 @@ * {@index pack200 pack200 tool} and * {@index unpack200 unpack200 tool} tools. * - *
- *
Tool Guides: - *
{@extLink pack200_tool_reference pack200}, - * {@extLink unpack200_tool_reference unpack200} - *
+ * @toolGuide pack200 + * @toolGuide unpack200 * * @moduleGraph * @deprecated This module is deprecated, and is planned for removal in a diff --git a/src/jdk.rmic/share/classes/module-info.java b/src/jdk.rmic/share/classes/module-info.java index 551c1bf577c..02f8edf943c 100644 --- a/src/jdk.rmic/share/classes/module-info.java +++ b/src/jdk.rmic/share/classes/module-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014, 2018, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2014, 2019, 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 @@ -27,10 +27,7 @@ * Defines the {@index rmic rmic} compiler for generating stubs and * skeletons using the Java Remote Method Protocol (JRMP) for remote objects. * - *
- *
Tool Guides: - *
{@extLink rmic_tool_reference rmic} - *
+ * @toolGuide rmic * * @moduleGraph * @since 9 diff --git a/src/jdk.scripting.nashorn.shell/share/classes/module-info.java b/src/jdk.scripting.nashorn.shell/share/classes/module-info.java index f7ddfbd8889..5bc8b0b71ea 100644 --- a/src/jdk.scripting.nashorn.shell/share/classes/module-info.java +++ b/src/jdk.scripting.nashorn.shell/share/classes/module-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2014, 2019, 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 @@ -29,10 +29,7 @@ *

This module includes the command line tool {@index jjs jjs tool} * to invoke the Nashorn engine. * - *

- *
Tool Guides: - *
{@extLink jjs_tool_reference jjs} - *
+ * @toolGuide jjs * * @moduleGraph * @since 9