# HG changeset patch # User jjg # Date 1497563130 25200 # Node ID 6a7b5298fcf59064e6d7307cd7468d04c1a95fc9 # Parent 6589d4088eaae70806be5a9cf8bccf276c618928 8181825: Add tool and services information to module summary Reviewed-by: mchung, rfield diff -r 6589d4088eaa -r 6a7b5298fcf5 langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/Main.java --- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/Main.java Thu Jun 15 17:24:13 2017 +0000 +++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/Main.java Thu Jun 15 14:45:30 2017 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2017, 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,8 +28,10 @@ import java.io.PrintWriter; /** - * The programmatic interface for the Java Programming Language + * A legacy programmatic interface for the Java Programming Language * compiler, javac. + * See the {@code jdk.compiler} + * module for details on replacement APIs. */ public class Main { diff -r 6589d4088eaa -r 6a7b5298fcf5 langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/package-info.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/package-info.java Thu Jun 15 14:45:30 2017 -0700 @@ -0,0 +1,31 @@ +/* + * Copyright (c) 2015, 2017, 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. + */ + +/** + * This package provides a legacy entry point for the javac tool. + * See the {@code jdk.compiler} + * module for details on replacement APIs. + */ +package com.sun.tools.javac; diff -r 6589d4088eaa -r 6a7b5298fcf5 langtools/src/jdk.compiler/share/classes/module-info.java --- a/langtools/src/jdk.compiler/share/classes/module-info.java Thu Jun 15 17:24:13 2017 +0000 +++ b/langtools/src/jdk.compiler/share/classes/module-info.java Thu Jun 15 14:45:30 2017 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014, 2016, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2014, 2017, 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 @@ -23,12 +23,63 @@ * questions. */ -/** Defines the implementation of the - * {@link javax.tools.ToolProvider#getSystemJavaCompiler system Java compiler} - * and its command line equivalent, javac, as well as javah. +/** + * Defines the implementation of the + * {@link javax.tools.ToolProvider#getSystemJavaCompiler system Java compiler} + * and its command line equivalent, {@index javac javac tool}, + * as well as {@index javah javah tool}. + * + *

javac

+ * + *

+ * This module provides the equivalent of command-line access to javac + * via the {@link java.util.spi.ToolProvider ToolProvider} and + * {@link javax.tools.Tool} service provider interfaces (SPIs), + * and more flexible access via the {@link javax.tools.JavaCompiler JavaCompiler} + * SPI.

+ * + *

Instances of the tools can be obtained by calling + * {@link java.util.spi.ToolProvider#findFirst ToolProvider.findFirst} + * or the {@link java.util.ServiceLoader service loader} with the name + * {@code "javac"}. + * + *

+ * In addition, instances of {@link javax.tools.JavaCompiler.CompilationTask} + * obtained from {@linkplain javax.tools.JavaCompiler JavaCompiler} can be + * downcast to {@link com.sun.source.util.JavacTask JavacTask} for access to + * lower level aspects of javac, such as the + * {@link com.sun.source.tree Abstract Syntax Tree} (AST).

* - * @moduleGraph - * @since 9 + *

This module uses the {@link java.nio.file.spi.FileSystemProvider + * FileSystemProvider} API to locate file system providers. In particular, + * this means that a jar file system provider, such as that in the + * {@code jdk.zipfs} module, must be available if the compiler is to be able + * to read JAR files. + * + *

javah

+ * + *

+ * javah only exists as a command line tool, and does not provide any + * direct API. As of JDK 9, it has been deprecated. + * Use the {@code -h} option in javac instead.

+ * + *
+ *
Tool Guides: + *
{@extLink javac_tool_reference javac}, + * {@extLink javah_tool_reference javah} + *
+ * + * @provides java.util.spi.ToolProvider + * @provides com.sun.tools.javac.platform.PlatformProvider + * @provides javax.tools.JavaCompiler + * @provides javax.tools.Tool + * + * @uses javax.annotation.processing.Processor + * @uses com.sun.source.util.Plugin + * @uses com.sun.tools.javac.platform.PlatformProvider + * + * @moduleGraph + * @since 9 */ module jdk.compiler { requires transitive java.compiler; diff -r 6589d4088eaa -r 6a7b5298fcf5 langtools/src/jdk.javadoc/share/classes/module-info.java --- a/langtools/src/jdk.javadoc/share/classes/module-info.java Thu Jun 15 17:24:13 2017 +0000 +++ b/langtools/src/jdk.javadoc/share/classes/module-info.java Thu Jun 15 14:45:30 2017 -0700 @@ -23,15 +23,39 @@ * questions. */ -/** Defines the implementation of the - * {@link javax.tools.ToolProvider#getSystemDocumentationTool system documentation tool} - * and its command line equivalent, javadoc. +/** + * Defines the implementation of the + * {@link javax.tools.ToolProvider#getSystemDocumentationTool system documentation tool} + * and its command line equivalent, {@index javadoc javadoc tool}. + * + *

javadoc

+ * + *

+ * This module provides the equivalent of command-line access to javadoc + * via the {@link java.util.spi.ToolProvider ToolProvider} and + * {@link javax.tools.Tool} service provider interfaces (SPIs), + * and more flexible access via the {@link javax.tools.DocumentationTool DocumentationTool} + * SPI.

* - * @see + *

Instances of the tools can be obtained by calling + * {@link java.util.spi.ToolProvider#findFirst ToolProvider.findFirst} + * or the {@link java.util.ServiceLoader service loader} with the name + * {@code "javadoc"}. + * + *

+ *
Tool Guides: + *
{@extLink javadoc_tool_reference javadoc} + *
+ * + * @provides java.util.spi.ToolProvider + * @provides javax.tools.DocumentationTool + * @provides javax.tools.Tool + * + * @see * Documentation Comment Specification for the Standard Doclet * - * @moduleGraph - * @since 9 + * @moduleGraph + * @since 9 */ module jdk.javadoc { requires transitive java.compiler; diff -r 6589d4088eaa -r 6a7b5298fcf5 langtools/src/jdk.jdeps/share/classes/module-info.java --- a/langtools/src/jdk.jdeps/share/classes/module-info.java Thu Jun 15 17:24:13 2017 +0000 +++ b/langtools/src/jdk.jdeps/share/classes/module-info.java Thu Jun 15 14:45:30 2017 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2015, 2016, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2015, 2017, 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 @@ -23,11 +23,38 @@ * questions. */ -/** Defines tools for analysing dependencies in Java libraries and programs, including - * the jdeps and javap tools. +/** + * Defines tools for analysing dependencies in Java libraries and programs, + * including the {@index jdeps jdeps tool}, + * {@index javap javap tool} and + * {@index jdeprscan jdeprscan tool} tools. + * + *

+ * This module provides the equivalent of command-line access to the + * javap and jdeps tools via the + * {@link java.util.spi.ToolProvider ToolProvider} service provider + * interface (SPI)

* - * @moduleGraph - * @since 9 + *

Instances of the tools can be obtained by calling + * {@link java.util.spi.ToolProvider#findFirst ToolProvider.findFirst} + * or the {@link java.util.ServiceLoader service loader} with the name + * {@code "javap"} or {@code "jdeps"} as appropriate. + * + *

+ * 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} + *
+ * + * @provides java.util.spi.ToolProvider + * + * @moduleGraph + * @since 9 */ module jdk.jdeps { requires java.base; diff -r 6589d4088eaa -r 6a7b5298fcf5 langtools/src/jdk.jshell/share/classes/module-info.java --- a/langtools/src/jdk.jshell/share/classes/module-info.java Thu Jun 15 17:24:13 2017 +0000 +++ b/langtools/src/jdk.jshell/share/classes/module-info.java Thu Jun 15 14:45:30 2017 -0700 @@ -25,10 +25,10 @@ /** * This module provides support for - * Java™ Programming Language 'snippet' evaluating tools, such as - * Read-Eval-Print Loops (REPLs). + * Java Programming Language 'snippet' evaluating tools, such as + * Read-Eval-Print Loops (REPLs), including the {@index jshell jshell tool} tool. * Separate packages support building tools, configuring the execution of tools, - * and programmatically launching the existing Java™ shell tool. + * and programmatically launching the existing Java shell tool. *

* The {@link jdk.jshell} is the package for creating 'snippet' evaluating tools. * Generally, this is only package that would be needed for creating tools. @@ -42,8 +42,8 @@ * implementations. *

*

- * The {@link jdk.jshell.tool} supports programmatically launching the - * "jshell tool". + * The {@link jdk.jshell.tool} package supports programmatically launching the + * jshell tool. *

*

* The {@link jdk.jshell.execution} package contains implementations of the @@ -52,6 +52,15 @@ * definitions. *

* + *
+ *
Tool Guides: + *
{@extLink jshell_tool_reference jshell} + *
+ * + * @provides javax.tools.Tool + * @provides jdk.jshell.spi.ExecutionControlProvider + * @uses jdk.jshell.spi.ExecutionControlProvider + * * @moduleGraph * @since 9 */