Skip to content

Commit 5a80abf

Browse files
jonathan-gibbonsjonathan-gibbons
committedDec 8, 2021
8272944: Use snippets in jdk.javadoc documentation
Reviewed-by: hannesw
·
JEP-429-branchpoint
1 parent fb11d8f commit 5a80abf

File tree

2 files changed

+147
-114
lines changed

2 files changed

+147
-114
lines changed
 

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

+6
Original file line numberDiff line numberDiff line change
@@ -757,6 +757,12 @@ public JavaFileObject getFileObjectOf(Element e) {
757757
*/
758758
private Pair<JCTree, JCCompilationUnit> getTreeAndTopLevel(Element e) {
759759
Symbol sym = cast(Symbol.class, e);
760+
if (sym.kind == PCK) {
761+
TypeSymbol pkgInfo = ((PackageSymbol) sym).package_info;
762+
if (pkgInfo != null) {
763+
pkgInfo.complete();
764+
}
765+
}
760766
Env<AttrContext> enterEnv = getEnterEnv(sym);
761767
if (enterEnv == null)
762768
return null;

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

+141-114
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2015, 2021, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -51,9 +51,9 @@
5151
* The invocation is defined by the interface {@link jdk.javadoc.doclet.Doclet}
5252
* -- the {@link jdk.javadoc.doclet.Doclet#run(DocletEnvironment) run} interface
5353
* method, defines the entry point.
54-
* <pre>
55-
* public boolean <b>run</b>(DocletEnvironment environment)
56-
* </pre>
54+
* {@snippet id="entry-point" lang=java :
55+
* public boolean run(DocletEnvironment environment) // @highlight substring="run"
56+
* }
5757
* The {@link jdk.javadoc.doclet.DocletEnvironment} instance holds the
5858
* environment that the doclet will be initialized with. From this environment
5959
* all other information can be extracted, in the form of
@@ -185,120 +185,147 @@
185185
*
186186
* The following is an example doclet that displays information of a class
187187
* and its members, supporting an option.
188-
* <pre>
189-
* // note imports deleted for clarity
188+
*
189+
* {@snippet lang=java id="Example.java" :
190+
* // @replace region=imports replacement=" // Note: imports deleted for clarity"
191+
* import com.sun.source.doctree.DocCommentTree;
192+
* import com.sun.source.util.DocTrees;
193+
* import jdk.javadoc.doclet.Doclet;
194+
* import jdk.javadoc.doclet.DocletEnvironment;
195+
* import jdk.javadoc.doclet.Reporter;
196+
*
197+
* import javax.lang.model.SourceVersion;
198+
* import javax.lang.model.element.Element;
199+
* import javax.lang.model.element.TypeElement;
200+
* import javax.lang.model.util.ElementFilter;
201+
* import javax.tools.Diagnostic.Kind;
202+
* import java.io.IOException;
203+
* import java.io.PrintWriter;
204+
* import java.util.List;
205+
* import java.util.Locale;
206+
* import java.util.Set;
207+
* // @end
208+
*
209+
*
190210
* public class Example implements Doclet {
191-
* Reporter reporter;
192-
* &#64;Override
193-
* public void init(Locale locale, Reporter reporter) {
194-
* reporter.print(Kind.NOTE, "Doclet using locale: " + locale);
195-
* this.reporter = reporter;
196-
* }
197-
*
198-
* public void printElement(DocTrees trees, Element e) {
199-
* DocCommentTree docCommentTree = trees.getDocCommentTree(e);
200-
* if (docCommentTree != null) {
201-
* System.out.println("Element (" + e.getKind() + ": "
202-
* + e + ") has the following comments:");
203-
* System.out.println("Entire body: " + docCommentTree.getFullBody());
204-
* System.out.println("Block tags: " + docCommentTree.getBlockTags());
205-
* }
206-
* }
207-
*
208-
* &#64;Override
209-
* public boolean run(DocletEnvironment docEnv) {
210-
* reporter.print(Kind.NOTE, "overviewfile: " + overviewfile);
211-
* // get the DocTrees utility class to access document comments
212-
* DocTrees docTrees = docEnv.getDocTrees();
213-
*
214-
* // location of an element in the same directory as overview.html
215-
* try {
216-
* Element e = ElementFilter.typesIn(docEnv.getSpecifiedElements()).iterator().next();
217-
* DocCommentTree docCommentTree
218-
* = docTrees.getDocCommentTree(e, overviewfile);
219-
* if (docCommentTree != null) {
220-
* System.out.println("Overview html: " + docCommentTree.getFullBody());
221-
* }
222-
* } catch (IOException missing) {
223-
* reporter.print(Kind.ERROR, "No overview.html found.");
224-
* }
225-
*
226-
* for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) {
227-
* System.out.println(t.getKind() + ":" + t);
228-
* for (Element e : t.getEnclosedElements()) {
229-
* printElement(docTrees, e);
230-
* }
231-
* }
232-
* return true;
233-
* }
234-
*
235-
* &#64;Override
236-
* public String getName() {
237-
* return "Example";
238-
* }
239-
*
240-
* private String overviewfile;
241-
*
242-
* &#64;Override
243-
* public Set&lt;? extends Option&gt; getSupportedOptions() {
244-
* Option[] options = {
245-
* new Option() {
246-
* private final List&lt;String&gt; someOption = Arrays.asList(
247-
* "-overviewfile",
248-
* "--overview-file",
249-
* "-o"
250-
* );
251-
*
252-
* &#64;Override
253-
* public int getArgumentCount() {
254-
* return 1;
255-
* }
256-
*
257-
* &#64;Override
258-
* public String getDescription() {
259-
* return "an option with aliases";
260-
* }
261-
*
262-
* &#64;Override
263-
* public Option.Kind getKind() {
264-
* return Option.Kind.STANDARD;
265-
* }
266-
*
267-
* &#64;Override
268-
* public List&lt;String&gt; getNames() {
269-
* return someOption;
270-
* }
271-
*
272-
* &#64;Override
273-
* public String getParameters() {
274-
* return "file";
275-
* }
276-
*
277-
* &#64;Override
278-
* public boolean process(String opt, List&lt;String&gt; arguments) {
279-
* overviewfile = arguments.get(0);
280-
* return true;
281-
* }
282-
* }
283-
* };
284-
* return new HashSet&lt;&gt;(Arrays.asList(options));
285-
* }
286-
*
287-
* &#64;Override
288-
* public SourceVersion getSupportedSourceVersion() {
289-
* // support the latest release
290-
* return SourceVersion.latest();
291-
* }
211+
* private Reporter reporter;
212+
* private PrintWriter stdout;
213+
*
214+
* @Override
215+
* public void init(Locale locale, Reporter reporter) {
216+
* reporter.print(Kind.NOTE, "Doclet using locale: " + locale);
217+
* this.reporter = reporter;
218+
* stdout = reporter.getStandardWriter();
219+
* }
220+
*
221+
* public void printElement(DocTrees trees, Element e) {
222+
* DocCommentTree docCommentTree = trees.getDocCommentTree(e);
223+
* if (docCommentTree != null) {
224+
* stdout.println("Element (" + e.getKind() + ": "
225+
* + e + ") has the following comments:");
226+
* stdout.println("Entire body: " + docCommentTree.getFullBody());
227+
* stdout.println("Block tags: " + docCommentTree.getBlockTags());
228+
* }
229+
* }
230+
*
231+
* @Override
232+
* public boolean run(DocletEnvironment docEnv) {
233+
* reporter.print(Kind.NOTE, "overviewFile: " + overviewFile);
234+
*
235+
* // get the DocTrees utility class to access document comments
236+
* DocTrees docTrees = docEnv.getDocTrees();
237+
*
238+
* // location of an element in the same directory as overview.html
239+
* try {
240+
* Element e = ElementFilter.typesIn(docEnv.getSpecifiedElements()).iterator().next();
241+
* DocCommentTree docCommentTree
242+
* = docTrees.getDocCommentTree(e, overviewFile);
243+
* if (docCommentTree != null) {
244+
* stdout.println("Overview html: " + docCommentTree.getFullBody());
245+
* }
246+
* } catch (IOException missing) {
247+
* reporter.print(Kind.ERROR, "No overview.html found.");
248+
* }
249+
*
250+
* for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) {
251+
* stdout.println(t.getKind() + ":" + t);
252+
* for (Element e : t.getEnclosedElements()) {
253+
* printElement(docTrees, e);
254+
* }
255+
* }
256+
* return true;
257+
* }
258+
*
259+
* @Override
260+
* public String getName() {
261+
* return "Example";
262+
* }
263+
*
264+
* private String overviewFile;
265+
*
266+
* @Override
267+
* public Set<? extends Option> getSupportedOptions() {
268+
* Option[] options = {
269+
* new Option() {
270+
* private final List<String> someOption = List.of(
271+
* "--overview-file",
272+
* "-overviewfile",
273+
* "-o"
274+
* );
275+
*
276+
* @Override
277+
* public int getArgumentCount() {
278+
* return 1;
279+
* }
280+
*
281+
* @Override
282+
* public String getDescription() {
283+
* return "an option with aliases";
284+
* }
285+
*
286+
* @Override
287+
* public Option.Kind getKind() {
288+
* return Option.Kind.STANDARD;
289+
* }
290+
*
291+
* @Override
292+
* public List<String> getNames() {
293+
* return someOption;
294+
* }
295+
*
296+
* @Override
297+
* public String getParameters() {
298+
* return "file";
299+
* }
300+
*
301+
* @Override
302+
* public boolean process(String opt, List<String> arguments) {
303+
* overviewFile = arguments.get(0);
304+
* return true;
305+
* }
306+
* }
307+
* };
308+
*
309+
* return Set.of(options);
310+
* }
311+
*
312+
* @Override
313+
* public SourceVersion getSupportedSourceVersion() {
314+
* // support the latest release
315+
* return SourceVersion.latest();
316+
* }
317+
* }
292318
* }
293-
* </pre>
319+
*
294320
* <p>
295321
* This doclet can be invoked with a command line, such as:
296-
* <pre>
297-
* javadoc -doclet Example &#92;
298-
* -overviewfile overview.html &#92;
299-
* -sourcepath source-location &#92;
300-
* source-location/Example.java
301-
* </pre>
322+
* {@snippet id="run-doclet":
323+
* javadoc -docletpath doclet-classes \ // @highlight substring="doclet-classes " type=italic
324+
* -doclet Example \
325+
* --overview-file overview.html \
326+
* --source-path source-location \ // @highlight region substring="source-location" type=italic
327+
* source-location/Example.java // @end
328+
* }
302329
*
303330
* <h2><a id="migration">Migration Guide</a></h2>
304331
*

0 commit comments

Comments
 (0)
Please sign in to comment.