DocTrees.java revision 3900:02e61db8289d
1/* 2 * Copyright (c) 2011, 2017, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package com.sun.source.util; 27 28import java.io.IOException; 29import java.text.BreakIterator; 30import java.util.List; 31 32import javax.annotation.processing.ProcessingEnvironment; 33import javax.lang.model.element.Element; 34import javax.lang.model.element.PackageElement; 35import javax.tools.Diagnostic; 36import javax.tools.FileObject; 37import javax.tools.JavaCompiler.CompilationTask; 38 39import com.sun.source.doctree.DocCommentTree; 40import com.sun.source.doctree.DocTree; 41 42/** 43 * Provides access to syntax trees for doc comments. 44 * 45 * @since 1.8 46 */ 47public abstract class DocTrees extends Trees { 48 /** 49 * Returns a DocTrees object for a given CompilationTask. 50 * @param task the compilation task for which to get the Trees object 51 * @return the DocTrees object 52 * @throws IllegalArgumentException if the task does not support the Trees API. 53 */ 54 public static DocTrees instance(CompilationTask task) { 55 return (DocTrees) Trees.instance(task); 56 } 57 58 /** 59 * Returns a DocTrees object for a given ProcessingEnvironment. 60 * @param env the processing environment for which to get the Trees object 61 * @return the DocTrees object 62 * @throws IllegalArgumentException if the env does not support the Trees API. 63 */ 64 public static DocTrees instance(ProcessingEnvironment env) { 65 if (!env.getClass().getName().equals("com.sun.tools.javac.processing.JavacProcessingEnvironment")) 66 throw new IllegalArgumentException(); 67 return (DocTrees) getJavacTrees(ProcessingEnvironment.class, env); 68 } 69 70 /** 71 * Returns the break iterator used to compute the first sentence of 72 * documentation comments. 73 * Returns {@code null} if none has been specified. 74 * @return the break iterator 75 * 76 * @since 9 77 */ 78 public abstract BreakIterator getBreakIterator(); 79 80 /** 81 * Returns the doc comment tree, if any, for the Tree node identified by a given TreePath. 82 * Returns {@code null} if no doc comment was found. 83 * @param path the path for the tree node 84 * @return the doc comment tree 85 */ 86 public abstract DocCommentTree getDocCommentTree(TreePath path); 87 88 /** 89 * Returns the doc comment tree of the given element. 90 * Returns {@code null} if no doc comment was found. 91 * @param e an element whose documentation is required 92 * @return the doc comment tree 93 * 94 * @since 9 95 */ 96 public abstract DocCommentTree getDocCommentTree(Element e); 97 98 /** 99 * Returns the doc comment tree of the given file. The file must be 100 * an HTML file, in which case the doc comment tree represents the 101 * contents of the <body> tag, and any enclosing tags are ignored. 102 * Returns {@code null} if no doc comment was found. 103 * Future releases may support additional file types. 104 * 105 * @param fileObject the content container 106 * @return the doc comment tree 107 * 108 * @since 9 109 */ 110 public abstract DocCommentTree getDocCommentTree(FileObject fileObject); 111 112 /** 113 * Returns the doc comment tree of the given file whose path is 114 * specified relative to the given element. The file must be an HTML 115 * file, in which case the doc comment tree represents the contents 116 * of the <body> tag, and any enclosing tags are ignored. 117 * Returns {@code null} if no doc comment was found. 118 * Future releases may support additional file types. 119 * 120 * @param e an element whose path is used as a reference 121 * @param relativePath the relative path from the Element 122 * @return the doc comment tree 123 * @throws java.io.IOException if an exception occurs 124 * 125 * @since 9 126 */ 127 public abstract DocCommentTree getDocCommentTree(Element e, String relativePath) throws IOException; 128 129 /** 130 * Returns a doc tree path containing the doc comment tree of the given file. 131 * The file must be an HTML file, in which case the doc comment tree represents 132 * the contents of the {@code <body>} tag, and any enclosing tags are ignored. 133 * Any references to source code elements contained in {@code @see} and 134 * {@code {@link}} tags in the doc comment tree will be evaluated in the 135 * context of the given package element. 136 * Returns {@code null} if no doc comment was found. 137 * 138 * @param fileObject a file object encapsulating the HTML content 139 * @param packageElement a package element to associate with the given file object 140 * representing a legacy package.html, null otherwise 141 * @return a doc tree path containing the doc comment parsed from the given file 142 * @throws IllegalArgumentException if the fileObject is not an HTML file 143 * 144 * @since 9 145 */ 146 public abstract DocTreePath getDocTreePath(FileObject fileObject, PackageElement packageElement); 147 148 /** 149 * Returns the language model element referred to by the leaf node of the given 150 * {@link DocTreePath}, or {@code null} if unknown. 151 * @param path the path for the tree node 152 * @return the element 153 */ 154 public abstract Element getElement(DocTreePath path); 155 156 /** 157 * Returns the list of {@link DocTree} representing the first sentence of 158 * a comment. 159 * 160 * @param list the DocTree list to interrogate 161 * @return the first sentence 162 * 163 * @since 9 164 */ 165 public abstract List<DocTree> getFirstSentence(List<? extends DocTree> list); 166 167 /** 168 * Returns a utility object for accessing the source positions 169 * of documentation tree nodes. 170 * @return the utility object 171 */ 172 public abstract DocSourcePositions getSourcePositions(); 173 174 /** 175 * Prints a message of the specified kind at the location of the 176 * tree within the provided compilation unit 177 * 178 * @param kind the kind of message 179 * @param msg the message, or an empty string if none 180 * @param t the tree to use as a position hint 181 * @param c the doc comment tree to use as a position hint 182 * @param root the compilation unit that contains tree 183 */ 184 public abstract void printMessage(Diagnostic.Kind kind, CharSequence msg, 185 com.sun.source.doctree.DocTree t, 186 com.sun.source.doctree.DocCommentTree c, 187 com.sun.source.tree.CompilationUnitTree root); 188 189 /** 190 * Sets the break iterator to compute the first sentence of 191 * documentation comments. 192 * @param breakiterator a break iterator or {@code null} to specify the default 193 * sentence breaker 194 * 195 * @since 9 196 */ 197 public abstract void setBreakIterator(BreakIterator breakiterator); 198 199 /** 200 * Returns a utility object for creating {@code DocTree} objects. 201 * @return a utility object for creating {@code DocTree} objects 202 * 203 * @since 9 204 */ 205 public abstract DocTreeFactory getDocTreeFactory(); 206} 207