--- 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 <a href="{@docRoot}/jdk.compiler-summary.html">{@code jdk.compiler}</a>
+ * module for details on replacement APIs.
  */
 public class Main {
 

--- /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 <em>javac</em> tool.
+ * See the <a href="{@docRoot}/jdk.compiler-summary.html">{@code jdk.compiler}</a>
+ * module for details on replacement APIs.
+ */
+package com.sun.tools.javac;

--- 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, <em>javac</em>, as well as <em>javah</em>.
+/**
+ * Defines the implementation of the
+ * {@link javax.tools.ToolProvider#getSystemJavaCompiler system Java compiler}
+ * and its command line equivalent, <em>{@index javac javac tool}</em>,
+ * as well as <em>{@index javah javah tool}</em>.
+ *
+ * <h2 style="font-family:'DejaVu Sans Mono', monospace; font-style:italic">javac</h2>
+ *
+ * <p>
+ * This module provides the equivalent of command-line access to <em>javac</em>
+ * 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.</p>
+ *
+ * <p> 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"}.
+ *
+ * <p>
+ * 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 <em>javac</em>, such as the
+ * {@link com.sun.source.tree Abstract Syntax Tree} (AST).</p>
  *
- *  @moduleGraph
- *  @since 9
+ * <p>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.
+ *
+ * <h2 style="font-family:'DejaVu Sans Mono', monospace; font-style:italic">javah</h2>
+ *
+ * <p>
+ * <em>javah</em> 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 <em>javac</em> instead.</p>
+ *
+ * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * <dt class="simpleTagLabel">Tool Guides:
+ * <dd>{@extLink javac_tool_reference javac},
+ *     {@extLink javah_tool_reference javah}
+ * </dl>
+ *
+ * @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;

--- 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, <em>javadoc</em>.
+/**
+ * Defines the implementation of the
+ * {@link javax.tools.ToolProvider#getSystemDocumentationTool system documentation tool}
+ * and its command line equivalent, <em>{@index javadoc javadoc tool}</em>.
+ *
+ * <h2 style="font-family:'DejaVu Sans Mono', monospace; font-style:italic">javadoc</h2>
+ *
+ * <p>
+ * This module provides the equivalent of command-line access to <em>javadoc</em>
+ * 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.</p>
  *
- *  @see <a href="{@docRoot}/../specs/doc-comment-spec.html">
+ * <p> 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"}.
+ *
+ * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * <dt class="simpleTagLabel">Tool Guides:
+ * <dd>{@extLink javadoc_tool_reference javadoc}
+ * </dl>
+ *
+ * @provides java.util.spi.ToolProvider
+ * @provides javax.tools.DocumentationTool
+ * @provides javax.tools.Tool
+ *
+ * @see <a href="{@docRoot}/../specs/doc-comment-spec.html">
  *      Documentation Comment Specification for the Standard Doclet</a>
  *
- *  @moduleGraph
- *  @since 9
+ * @moduleGraph
+ * @since 9
  */
 module jdk.javadoc {
     requires transitive java.compiler;

--- 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 <em>jdeps</em> and <em>javap</em> tools.
+/**
+ * Defines tools for analysing dependencies in Java libraries and programs,
+ * including the <em>{@index jdeps jdeps tool}</em>,
+ * <em>{@index javap javap tool}</em> and
+ * <em>{@index jdeprscan jdeprscan tool}</em> tools.
+ *
+ * <p>
+ * This module provides the equivalent of command-line access to the
+ * <em>javap</em> and <em>jdeps</em> tools via the
+ * {@link java.util.spi.ToolProvider ToolProvider} service provider
+ * interface (SPI)</p>
  *
- *  @moduleGraph
- *  @since 9
+ * <p> 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.
+ *
+ * <p>
+ * <em>jdeprscan</em> only exists as a command line tool, and does not provide
+ * any direct API.
+ *
+ * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * <dt class="simpleTagLabel">Tool Guides:
+ * <dd>{@extLink javap_tool_reference javap},
+ *     {@extLink jdeprscan_tool_reference jdeprscan},
+ *     {@extLink jdeps_tool_reference jdeps}
+ * </dl>
+ *
+ * @provides java.util.spi.ToolProvider
+ *
+ * @moduleGraph
+ * @since 9
  */
 module jdk.jdeps {
     requires java.base;

--- 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 <em>{@index jshell jshell tool}</em> tool.
  * Separate packages support building tools, configuring the execution of tools,
- * and programmatically launching the existing Java&#x2122; shell tool.
+ * and programmatically launching the existing Java shell tool.
  * <p>
  *     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.
  * </p>
  * <p>
- *     The {@link jdk.jshell.tool} supports programmatically launching the
- *     "jshell tool".
+ *     The {@link jdk.jshell.tool} package supports programmatically launching the
+ *     <em>jshell</em> tool.
  * </p>
  * <p>
  *     The {@link jdk.jshell.execution} package contains implementations of the
@@ -52,6 +52,15 @@
  *     definitions.
  * </p>
  *
+ * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * <dt class="simpleTagLabel">Tool Guides:
+ * <dd>{@extLink jshell_tool_reference jshell}
+ * </dl>
+ *
+ * @provides javax.tools.Tool
+ * @provides jdk.jshell.spi.ExecutionControlProvider
+ * @uses jdk.jshell.spi.ExecutionControlProvider
+ *
  * @moduleGraph
  * @since 9
  */