8272944: Use snippets in jdk.javadoc documentation

Reviewed-by: hannesw

src/jdk.compiler/share/classes/com/sun/tools/javac/model/JavacElements.java

@@ -757,6 +757,12 @@ public class JavacElements implements Elements {
      */
     private Pair<JCTree, JCCompilationUnit> getTreeAndTopLevel(Element e) {
         Symbol sym = cast(Symbol.class, e);
+        if (sym.kind == PCK) {
+            TypeSymbol pkgInfo = ((PackageSymbol) sym).package_info;
+            if (pkgInfo != null) {
+                pkgInfo.complete();
+            }
+        }
         Env<AttrContext> enterEnv = getEnterEnv(sym);
         if (enterEnv == null)
             return null;

src/jdk.javadoc/share/classes/jdk/javadoc/doclet/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2021, 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
@@ -51,9 +51,9 @@
  * The invocation is defined by the interface {@link jdk.javadoc.doclet.Doclet}
  * -- the {@link jdk.javadoc.doclet.Doclet#run(DocletEnvironment) run} interface
  * method, defines the entry point.
- * <pre>
+ * {@snippet id="entry-point" lang=java :
- *    public boolean <b>run</b>(DocletEnvironment environment)
+ *    public boolean run(DocletEnvironment environment) // @highlight substring="run"
- * </pre>
+ * }
  * The {@link jdk.javadoc.doclet.DocletEnvironment} instance holds the
  * environment that the doclet will be initialized with. From this environment
  * all other information can be extracted, in the form of
@@ -185,120 +185,147 @@
  *
  * The following is an example doclet that displays information of a class
  * and its members, supporting an option.
- * <pre>
+ *
- * // note imports deleted for clarity
+ * {@snippet lang=java id="Example.java" :
+ * // @replace region=imports replacement=" // Note: imports deleted for clarity"
+ * import com.sun.source.doctree.DocCommentTree;
+ * import com.sun.source.util.DocTrees;
+ * import jdk.javadoc.doclet.Doclet;
+ * import jdk.javadoc.doclet.DocletEnvironment;
+ * import jdk.javadoc.doclet.Reporter;
+ *
+ * import javax.lang.model.SourceVersion;
+ * import javax.lang.model.element.Element;
+ * import javax.lang.model.element.TypeElement;
+ * import javax.lang.model.util.ElementFilter;
+ * import javax.tools.Diagnostic.Kind;
+ * import java.io.IOException;
+ * import java.io.PrintWriter;
+ * import java.util.List;
+ * import java.util.Locale;
+ * import java.util.Set;
+ * // @end
+ *
+ *
  * public class Example implements Doclet {
- *    Reporter reporter;
+ *     private Reporter reporter;
- *    &#64;Override
+ *     private PrintWriter stdout;
- *    public void init(Locale locale, Reporter reporter) {
- *        reporter.print(Kind.NOTE, "Doclet using locale: " + locale);
- *        this.reporter = reporter;
- *    }
  *
- *    public void printElement(DocTrees trees, Element e) {
+ *     @Override
- *        DocCommentTree docCommentTree = trees.getDocCommentTree(e);
+ *     public void init(Locale locale, Reporter reporter) {
- *        if (docCommentTree != null) {
+ *         reporter.print(Kind.NOTE, "Doclet using locale: " + locale);
- *            System.out.println("Element (" + e.getKind() + ": "
+ *         this.reporter = reporter;
- *                    + e + ") has the following comments:");
+ *         stdout = reporter.getStandardWriter();
- *            System.out.println("Entire body: " + docCommentTree.getFullBody());
+ *     }
- *            System.out.println("Block tags: " + docCommentTree.getBlockTags());
- *        }
- *    }
  *
- *    &#64;Override
+ *     public void printElement(DocTrees trees, Element e) {
- *    public boolean run(DocletEnvironment docEnv) {
+ *         DocCommentTree docCommentTree = trees.getDocCommentTree(e);
- *        reporter.print(Kind.NOTE, "overviewfile: " + overviewfile);
+ *         if (docCommentTree != null) {
- *        // get the DocTrees utility class to access document comments
+ *             stdout.println("Element (" + e.getKind() + ": "
- *        DocTrees docTrees = docEnv.getDocTrees();
+ *                     + e + ") has the following comments:");
+ *             stdout.println("Entire body: " + docCommentTree.getFullBody());
+ *             stdout.println("Block tags: " + docCommentTree.getBlockTags());
+ *         }
+ *     }
  *
- *        // location of an element in the same directory as overview.html
+ *     @Override
- *        try {
+ *     public boolean run(DocletEnvironment docEnv) {
- *            Element e = ElementFilter.typesIn(docEnv.getSpecifiedElements()).iterator().next();
+ *         reporter.print(Kind.NOTE, "overviewFile: " + overviewFile);
- *            DocCommentTree docCommentTree
- *                    = docTrees.getDocCommentTree(e, overviewfile);
- *            if (docCommentTree != null) {
- *                System.out.println("Overview html: " + docCommentTree.getFullBody());
- *            }
- *        } catch (IOException missing) {
- *            reporter.print(Kind.ERROR, "No overview.html found.");
- *        }
  *
- *        for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) {
+ *         // get the DocTrees utility class to access document comments
- *            System.out.println(t.getKind() + ":" + t);
+ *         DocTrees docTrees = docEnv.getDocTrees();
- *            for (Element e : t.getEnclosedElements()) {
- *                printElement(docTrees, e);
- *            }
- *        }
- *        return true;
- *    }
  *
- *    &#64;Override
+ *         // location of an element in the same directory as overview.html
- *    public String getName() {
+ *         try {
- *        return "Example";
+ *             Element e = ElementFilter.typesIn(docEnv.getSpecifiedElements()).iterator().next();
- *    }
+ *             DocCommentTree docCommentTree
+ *                     = docTrees.getDocCommentTree(e, overviewFile);
+ *             if (docCommentTree != null) {
+ *                 stdout.println("Overview html: " + docCommentTree.getFullBody());
+ *             }
+ *         } catch (IOException missing) {
+ *             reporter.print(Kind.ERROR, "No overview.html found.");
+ *         }
  *
- *    private String overviewfile;
+ *         for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) {
+ *             stdout.println(t.getKind() + ":" + t);
+ *             for (Element e : t.getEnclosedElements()) {
+ *                 printElement(docTrees, e);
+ *             }
+ *         }
+ *         return true;
+ *     }
  *
- *    &#64;Override
+ *     @Override
- *    public Set&lt;? extends Option&gt; getSupportedOptions() {
+ *     public String getName() {
- *        Option[] options = {
+ *         return "Example";
- *            new Option() {
+ *     }
- *                private final List&lt;String&gt; someOption = Arrays.asList(
- *                        "-overviewfile",
- *                        "--overview-file",
- *                        "-o"
- *                );
  *
- *                &#64;Override
+ *     private String overviewFile;
- *                public int getArgumentCount() {
- *                    return 1;
- *                }
  *
- *                &#64;Override
+ *     @Override
- *                public String getDescription() {
+ *     public Set<? extends Option> getSupportedOptions() {
- *                    return "an option with aliases";
+ *         Option[] options = {
- *                }
+ *             new Option() {
+ *                 private final List<String> someOption = List.of(
+ *                         "--overview-file",
+ *                         "-overviewfile",
+ *                         "-o"
+ *                 );
  *
- *                &#64;Override
+ *                 @Override
- *                public Option.Kind getKind() {
+ *                 public int getArgumentCount() {
- *                    return Option.Kind.STANDARD;
+ *                     return 1;
- *                }
+ *                 }
  *
- *                &#64;Override
+ *                 @Override
- *                public List&lt;String&gt; getNames() {
+ *                 public String getDescription() {
- *                    return someOption;
+ *                     return "an option with aliases";
- *                }
+ *                 }
  *
- *                &#64;Override
+ *                 @Override
- *                public String getParameters() {
+ *                 public Option.Kind getKind() {
- *                    return "file";
+ *                     return Option.Kind.STANDARD;
- *                }
+ *                 }
  *
- *                &#64;Override
+ *                 @Override
- *                public boolean process(String opt, List&lt;String&gt; arguments) {
+ *                 public List<String> getNames() {
- *                    overviewfile = arguments.get(0);
+ *                     return someOption;
- *                    return true;
+ *                 }
- *                }
- *            }
- *        };
- *        return new HashSet&lt;&gt;(Arrays.asList(options));
- *    }
  *
- *    &#64;Override
+ *                 @Override
- *    public SourceVersion getSupportedSourceVersion() {
+ *                 public String getParameters() {
- *        // support the latest release
+ *                     return "file";
- *        return SourceVersion.latest();
+ *                 }
- *    }
+ *
+ *                 @Override
+ *                 public boolean process(String opt, List<String> arguments) {
+ *                     overviewFile = arguments.get(0);
+ *                     return true;
+ *                 }
+ *             }
+ *         };
+ *
+ *         return Set.of(options);
+ *     }
+ *
+ *     @Override
+ *     public SourceVersion getSupportedSourceVersion() {
+ *         // support the latest release
+ *         return SourceVersion.latest();
+ *     }
  * }
- * </pre>
+ * }
+ *
  * <p>
  * This doclet can be invoked with a command line, such as:
- * <pre>
+ * {@snippet id="run-doclet":
- *     javadoc -doclet Example &#92;
+ *     javadoc -docletpath doclet-classes \     // @highlight substring="doclet-classes " type=italic
- *       -overviewfile overview.html &#92;
+ *       -doclet Example \
- *       -sourcepath source-location &#92;
+ *       --overview-file overview.html \
- *       source-location/Example.java
+ *       --source-path source-location \        // @highlight region substring="source-location" type=italic
- * </pre>
+ *       source-location/Example.java           // @end
+ *     }
  *
  * <h2><a id="migration">Migration Guide</a></h2>
  *