DocTreeFactory.java revision 3209:1203d1d370e2
1171176Smlaier/* 2171176Smlaier * Copyright (c) 2011, 2016, Oracle and/or its affiliates. All rights reserved. 3171176Smlaier * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4171176Smlaier * 5171176Smlaier * This code is free software; you can redistribute it and/or modify it 6171176Smlaier * under the terms of the GNU General Public License version 2 only, as 7171176Smlaier * published by the Free Software Foundation. Oracle designates this 8171176Smlaier * particular file as subject to the "Classpath" exception as provided 9171176Smlaier * by Oracle in the LICENSE file that accompanied this code. 10171176Smlaier * 11171176Smlaier * This code is distributed in the hope that it will be useful, but WITHOUT 12171176Smlaier * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13171176Smlaier * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14171176Smlaier * version 2 for more details (a copy is included in the LICENSE file that 15171176Smlaier * accompanied this code). 16171176Smlaier * 17171176Smlaier * You should have received a copy of the GNU General Public License version 18171176Smlaier * 2 along with this work; if not, write to the Free Software Foundation, 19171176Smlaier * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20171176Smlaier * 21171176Smlaier * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22171176Smlaier * or visit www.oracle.com if you need additional information or have any 23171176Smlaier * questions. 24171176Smlaier */ 25171176Smlaier 26171176Smlaierpackage com.sun.source.util; 27171176Smlaier 28171176Smlaierimport java.util.List; 29171176Smlaier 30171176Smlaierimport javax.lang.model.element.Name; 31171176Smlaierimport javax.tools.Diagnostic; 32171176Smlaierimport javax.tools.JavaFileObject; 33171176Smlaier 34171176Smlaierimport com.sun.source.doctree.AttributeTree; 35171176Smlaierimport com.sun.source.doctree.AttributeTree.ValueKind; 36171176Smlaierimport com.sun.source.doctree.AuthorTree; 37171176Smlaierimport com.sun.source.doctree.CommentTree; 38171176Smlaierimport com.sun.source.doctree.DeprecatedTree; 39171176Smlaierimport com.sun.source.doctree.DocCommentTree; 40171176Smlaierimport com.sun.source.doctree.DocRootTree; 41171176Smlaierimport com.sun.source.doctree.DocTree; 42171176Smlaierimport com.sun.source.doctree.EndElementTree; 43171176Smlaierimport com.sun.source.doctree.EntityTree; 44171176Smlaierimport com.sun.source.doctree.ErroneousTree; 45171176Smlaierimport com.sun.source.doctree.IdentifierTree; 46171176Smlaierimport com.sun.source.doctree.IndexTree; 47171176Smlaierimport com.sun.source.doctree.InheritDocTree; 48171176Smlaierimport com.sun.source.doctree.LinkTree; 49171176Smlaierimport com.sun.source.doctree.LiteralTree; 50171176Smlaierimport com.sun.source.doctree.ParamTree; 51171176Smlaierimport com.sun.source.doctree.ReferenceTree; 52171176Smlaierimport com.sun.source.doctree.ReturnTree; 53171176Smlaierimport com.sun.source.doctree.SeeTree; 54171176Smlaierimport com.sun.source.doctree.SerialDataTree; 55171176Smlaierimport com.sun.source.doctree.SerialFieldTree; 56171176Smlaierimport com.sun.source.doctree.SerialTree; 57171176Smlaierimport com.sun.source.doctree.SinceTree; 58171176Smlaierimport com.sun.source.doctree.StartElementTree; 59171176Smlaierimport com.sun.source.doctree.TextTree; 60171176Smlaierimport com.sun.source.doctree.ThrowsTree; 61171176Smlaierimport com.sun.source.doctree.UnknownBlockTagTree; 62171176Smlaierimport com.sun.source.doctree.UnknownInlineTagTree; 63171176Smlaierimport com.sun.source.doctree.ValueTree; 64171176Smlaierimport com.sun.source.doctree.VersionTree; 65171176Smlaier 66171176Smlaier/** 67171176Smlaier * Factory for creating {@code DocTree} nodes. 68171176Smlaier * 69171176Smlaier * @implNote The methods in an implementation of this interface may only accept {@code DocTree} 70171176Smlaier * nodes that have been created by the same implementation. 71171176Smlaier * 72171176Smlaier * @since 9 73171176Smlaier */ 74171176Smlaierpublic interface DocTreeFactory { 75171176Smlaier /** 76171176Smlaier * Create a new {@code AttributeTree} object, to represent an HTML attribute in an HTML tag. 77171176Smlaier * @param name the name of the attribute 78171176Smlaier * @param vkind the kind of attribute value 79171176Smlaier * @param value the value, if any, of the attribute 80171176Smlaier * @return an {@code AttributeTree} object 81171176Smlaier */ 82171176Smlaier AttributeTree newAttributeTree(Name name, ValueKind vkind, List<? extends DocTree> value); 83171176Smlaier 84171176Smlaier /** 85171176Smlaier * Create a new {@code AuthorTree} object, to represent an {@code {@author } } tag. 86171176Smlaier * @param name the name of the author 87171176Smlaier * @return an {@code AuthorTree} object 88171176Smlaier */ 89171176Smlaier AuthorTree newAuthorTree(List<? extends DocTree> name); 90171176Smlaier 91171176Smlaier /** 92171176Smlaier * Create a new {@code CodeTree} object, to represent a {@code {@code } } tag. 93171176Smlaier * @param text the content of the tag 94171176Smlaier * @return a {@code CodeTree} object 95171176Smlaier */ 96171176Smlaier LiteralTree newCodeTree(TextTree text); 97171176Smlaier 98171176Smlaier /** 99171176Smlaier * Create a new {@code CommentTree}, to represent an HTML comment. 100171176Smlaier * @param text the content of the comment 101171176Smlaier * @return a {@code CommentTree} object 102171176Smlaier */ 103171176Smlaier CommentTree newCommentTree(String text); 104171176Smlaier 105171176Smlaier /** 106171176Smlaier * Create a new {@code DeprecatedTree} object, to represent an {@code {@deprecated } } tag. 107171176Smlaier * @param text the content of the tag 108171176Smlaier * @return a {@code DeprecatedTree} object 109171176Smlaier */ 110171176Smlaier DeprecatedTree newDeprecatedTree(List<? extends DocTree> text); 111171176Smlaier 112171176Smlaier /** 113171176Smlaier * Create a new {@code DocCommentTree} object, to represent a complete doc comment. 114171176Smlaier * @param firstSentence the first sentence of the doc comment 115171176Smlaier * @param body the body of the doc comment following the first sentence 116 * @param tags the block tags in the doc comment 117 * @return a {@code DocCommentTree} object 118 */ 119 DocCommentTree newDocCommentTree(List<? extends DocTree> firstSentence, List<? extends DocTree> body, List<? extends DocTree> tags); 120 121 /** 122 * Create a new {@code DocRootTree} object, to represent an {@code {@docroot} } tag. 123 * @return a {@code DocRootTree} object 124 */ 125 DocRootTree newDocRootTree(); 126 127 /** 128 * Create a new {@code EndElement} object, to represent the end of an HTML element. 129 * @param name the name of the HTML element 130 * @return an {@code EndElementTree} object 131 */ 132 EndElementTree newEndElementTree(Name name); 133 134 /** 135 * Create a new {@code EntityTree} object, to represent an HTML entity. 136 * @param name the name of the entity, representing the characters between '<' and ';' 137 * in the representation of the entity in an HTML document 138 * @return an {@code EntityTree} object 139 */ 140 EntityTree newEntityTree(Name name); 141 142 /** 143 * Create a new {@code ErroneousTree} object, to represent some unparseable input. 144 * @param text the unparseable text 145 * @param diag a diagnostic associated with the unparseable text, or null 146 * @return an {@code ErroneousTree} object 147 */ 148 ErroneousTree newErroneousTree(String text, Diagnostic<JavaFileObject> diag); 149 150 /** 151 * Create a new {@code ExceptionTree} object, to represent an {@code @exception } tag. 152 * @param name the name of the exception 153 * @param description a description of why the exception might be thrown 154 * @return an {@code ExceptionTree} object 155 */ 156 ThrowsTree newExceptionTree(ReferenceTree name, List<? extends DocTree> description); 157 158 /** 159 * Create a new {@code IdentifierTree} object, to represent an identifier, such as in a 160 * {@code @param } tag. 161 * @param name the name of the identifier 162 * @return an {@code IdentifierTree} object 163 */ 164 IdentifierTree newIdentifierTree(Name name); 165 166 /** 167 * Create a new {@code IndexTree} object, to represent an {@code {@index } } tag. 168 * @param term the search term 169 * @param description an optional description of the search term 170 * @return an {@code IndexTree} object 171 */ 172 IndexTree newIndexTree(DocTree term, List<? extends DocTree> description); 173 174 /** 175 * Create a new {@code InheritDocTree} object, to represent an {@code {@inheritDoc} } tag. 176 * @return an {@code InheritDocTree} object 177 */ 178 InheritDocTree newInheritDocTree(); 179 180 /** 181 * Create a new {@code LinkTree} object, to represent a {@code {@link } } tag. 182 * @param ref the API element being referenced 183 * @param label an optional label for the link 184 * @return a {@code LinkTree} object 185 */ 186 LinkTree newLinkTree(ReferenceTree ref, List<? extends DocTree> label); 187 188 /** 189 * Create a new {@code LinkPlainTree} object, to represent a {@code {@linkplain } } tag. 190 * @param ref the API element being referenced 191 * @param label an optional label for the link 192 * @return a {@code LinkPlainTree} object 193 */ 194 LinkTree newLinkPlainTree(ReferenceTree ref, List<? extends DocTree> label); 195 196 /** 197 * Create a new {@code LiteralTree} object, to represent a {@code {@literal } } tag. 198 * @param text the content of the tag 199 * @return a {@code LiteralTree} object 200 */ 201 LiteralTree newLiteralTree(TextTree text); 202 203 /** 204 * Create a new {@code ParamTree} object, to represent a {@code @param } tag. 205 * @param isTypeParameter true if this is a type parameter, and false otherwise 206 * @param name the parameter being described 207 * @param description the description of the parameter 208 * @return a {@code ParamTree} object 209 */ 210 ParamTree newParamTree(boolean isTypeParameter, IdentifierTree name, List<? extends DocTree> description); 211 212 /** 213 * Create a new {@code ReferenceTree} object, to represent a reference to an API element. 214 * 215 * @param signature the doc comment signature of the reference 216 * @return a {@code ReferenceTree} object 217 */ 218 ReferenceTree newReferenceTree(String signature); 219 220 /** 221 * Create a new {@code ReturnTree} object, to represent a {@code @return } tag. 222 * @param description the description of the return value of a method 223 * @return a {@code ReturnTree} object 224 */ 225 ReturnTree newReturnTree(List<? extends DocTree> description); 226 227 /** 228 * Create a new {@code SeeTree} object, to represent a {@code @see } tag. 229 * @param reference the reference 230 * @return a {@code SeeTree} object 231 */ 232 SeeTree newSeeTree(List<? extends DocTree> reference); 233 234 /** 235 * Create a new {@code SerialTree} object, to represent a {@code @serial } tag. 236 * @param description the description for the tag 237 * @return a {@code SerialTree} object 238 */ 239 SerialTree newSerialTree(List<? extends DocTree> description); 240 241 /** 242 * Create a new {@code SerialDataTree} object, to represent a {@code @serialData } tag. 243 * @param description the description for the tag 244 * @return a {@code SerialDataTree} object 245 */ 246 SerialDataTree newSerialDataTree(List<? extends DocTree> description); 247 248 /** 249 * Create a new {@code SerialFieldTree} object, to represent a {@code @serialField } tag. 250 * @param name the name of the field 251 * @param type the type of the field 252 * @param description the description of the field 253 * @return a {@code SerialFieldTree} object 254 */ 255 SerialFieldTree newSerialFieldTree(IdentifierTree name, ReferenceTree type, List<? extends DocTree> description); 256 257 /** 258 * Create a new {@code SinceTree} object, to represent a {@code @since } tag. 259 * @param text the content of the tag 260 * @return a {@code SinceTree} object 261 */ 262 SinceTree newSinceTree(List<? extends DocTree> text); 263 264 /** 265 * Create a new {@code StartElementTree} object, to represent the start of an HTML element. 266 * @param name the name of the HTML element 267 * @param attrs the attributes 268 * @param selfClosing true if the start element is marked as self-closing; otherwise false 269 * @return a {@code StartElementTree} object 270 */ 271 StartElementTree newStartElementTree(Name name, List<? extends DocTree> attrs, boolean selfClosing); 272 273 /** 274 * Create a new {@code TextTree} object, to represent some plain text. 275 * @param text the text 276 * @return a {@code TextTree} object 277 */ 278 TextTree newTextTree(String text); 279 280 /** 281 * Create a new {@code ThrowsTree} object, to represent a {@code @throws } tag. 282 * @param name the name of the exception 283 * @param description a description of why the exception might be thrown 284 * @return a {@code ThrowsTree} object 285 */ 286 ThrowsTree newThrowsTree(ReferenceTree name, List<? extends DocTree> description); 287 288 /** 289 * Create a new {@code UnknownBlockTagTree} object, to represent an unrecognized block tag. 290 * @param name the name of the block tag 291 * @param content the content 292 * @return an {@code UnknownBlockTagTree} object 293 */ 294 UnknownBlockTagTree newUnknownBlockTagTree(Name name, List<? extends DocTree> content); 295 296 /** 297 * Create a new {@code UnknownInlineTagTree} object, to represent an unrecognized inline tag. 298 * @param name the name of the inline tag 299 * @param content the content 300 * @return an {@code UnknownInlineTagTree} object 301 */ 302 UnknownInlineTagTree newUnknownInlineTagTree(Name name, List<? extends DocTree> content); 303 304 /** 305 * Create a new {@code ValueTree} object, to represent a {@code {@value } } tag. 306 * @param ref a reference to the value 307 * @return a {@code ValueTree} object 308 */ 309 ValueTree newValueTree(ReferenceTree ref); 310 311 /** 312 * Create a new {@code VersionTree} object, to represent a {@code {@version } } tag. 313 * @param text the content of the tag 314 * @return a {@code VersionTree} object 315 */ 316 VersionTree newVersionTree(List<? extends DocTree> text); 317 318 /** 319 * Set the position to be recorded in subsequent tree nodes created by this factory. 320 * The position should be a character offset relative to the beginning of the source file 321 * or {@link javax.tools.Diagnostic#NOPOS NOPOS}. 322 * @param pos the position 323 * @return this object, to facilitate method chaining 324 */ 325 DocTreeFactory at(int pos); 326 327 /** 328 * Get the first sentence contained in a list of content. 329 * The determination of the first sentence is implementation specific, and may 330 * involve the use of a locale-specific {@link java.text.BreakIterator BreakIterator} 331 * and other heuristics. 332 * The resulting list may share a common set of initial items with the input list. 333 * @param list the list 334 * @return a list containing the first sentence of the list. 335 */ 336 List<DocTree> getFirstSentence(List<? extends DocTree> list); 337 338} 339