DocTreeFactory.java revision 3337:cba09a2e6ae9
1/* 2 * Copyright (c) 2011, 2016, 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.util.List; 29 30import javax.lang.model.element.Name; 31import javax.tools.Diagnostic; 32import javax.tools.JavaFileObject; 33 34import com.sun.source.doctree.AttributeTree; 35import com.sun.source.doctree.AttributeTree.ValueKind; 36import com.sun.source.doctree.AuthorTree; 37import com.sun.source.doctree.CommentTree; 38import com.sun.source.doctree.DeprecatedTree; 39import com.sun.source.doctree.DocCommentTree; 40import com.sun.source.doctree.DocRootTree; 41import com.sun.source.doctree.DocTree; 42import com.sun.source.doctree.EndElementTree; 43import com.sun.source.doctree.EntityTree; 44import com.sun.source.doctree.ErroneousTree; 45import com.sun.source.doctree.HiddenTree; 46import com.sun.source.doctree.IdentifierTree; 47import com.sun.source.doctree.IndexTree; 48import com.sun.source.doctree.InheritDocTree; 49import com.sun.source.doctree.LinkTree; 50import com.sun.source.doctree.LiteralTree; 51import com.sun.source.doctree.ParamTree; 52import com.sun.source.doctree.ReferenceTree; 53import com.sun.source.doctree.ReturnTree; 54import com.sun.source.doctree.SeeTree; 55import com.sun.source.doctree.SerialDataTree; 56import com.sun.source.doctree.SerialFieldTree; 57import com.sun.source.doctree.SerialTree; 58import com.sun.source.doctree.SinceTree; 59import com.sun.source.doctree.StartElementTree; 60import com.sun.source.doctree.TextTree; 61import com.sun.source.doctree.ThrowsTree; 62import com.sun.source.doctree.UnknownBlockTagTree; 63import com.sun.source.doctree.UnknownInlineTagTree; 64import com.sun.source.doctree.ValueTree; 65import com.sun.source.doctree.VersionTree; 66 67/** 68 * Factory for creating {@code DocTree} nodes. 69 * 70 * @implNote The methods in an implementation of this interface may only accept {@code DocTree} 71 * nodes that have been created by the same implementation. 72 * 73 * @since 9 74 */ 75public interface DocTreeFactory { 76 /** 77 * Create a new {@code AttributeTree} object, to represent an HTML attribute in an HTML tag. 78 * @param name the name of the attribute 79 * @param vkind the kind of attribute value 80 * @param value the value, if any, of the attribute 81 * @return an {@code AttributeTree} object 82 */ 83 AttributeTree newAttributeTree(Name name, ValueKind vkind, List<? extends DocTree> value); 84 85 /** 86 * Create a new {@code AuthorTree} object, to represent an {@code {@author } } tag. 87 * @param name the name of the author 88 * @return an {@code AuthorTree} object 89 */ 90 AuthorTree newAuthorTree(List<? extends DocTree> name); 91 92 /** 93 * Create a new {@code CodeTree} object, to represent a {@code {@code } } tag. 94 * @param text the content of the tag 95 * @return a {@code CodeTree} object 96 */ 97 LiteralTree newCodeTree(TextTree text); 98 99 /** 100 * Create a new {@code CommentTree}, to represent an HTML comment. 101 * @param text the content of the comment 102 * @return a {@code CommentTree} object 103 */ 104 CommentTree newCommentTree(String text); 105 106 /** 107 * Create a new {@code DeprecatedTree} object, to represent an {@code {@deprecated } } tag. 108 * @param text the content of the tag 109 * @return a {@code DeprecatedTree} object 110 */ 111 DeprecatedTree newDeprecatedTree(List<? extends DocTree> text); 112 113 /** 114 * Create a new {@code DocCommentTree} object, to represent a complete doc comment. 115 * @param firstSentence the first sentence of the doc comment 116 * @param body the body of the doc comment following the first sentence 117 * @param tags the block tags in the doc comment 118 * @return a {@code DocCommentTree} object 119 */ 120 DocCommentTree newDocCommentTree(List<? extends DocTree> firstSentence, List<? extends DocTree> body, List<? extends DocTree> tags); 121 122 /** 123 * Create a new {@code DocRootTree} object, to represent an {@code {@docroot} } tag. 124 * @return a {@code DocRootTree} object 125 */ 126 DocRootTree newDocRootTree(); 127 128 /** 129 * Create a new {@code EndElement} object, to represent the end of an HTML element. 130 * @param name the name of the HTML element 131 * @return an {@code EndElementTree} object 132 */ 133 EndElementTree newEndElementTree(Name name); 134 135 /** 136 * Create a new {@code EntityTree} object, to represent an HTML entity. 137 * @param name the name of the entity, representing the characters between '<' and ';' 138 * in the representation of the entity in an HTML document 139 * @return an {@code EntityTree} object 140 */ 141 EntityTree newEntityTree(Name name); 142 143 /** 144 * Create a new {@code ErroneousTree} object, to represent some unparseable input. 145 * @param text the unparseable text 146 * @param diag a diagnostic associated with the unparseable text, or null 147 * @return an {@code ErroneousTree} object 148 */ 149 ErroneousTree newErroneousTree(String text, Diagnostic<JavaFileObject> diag); 150 151 /** 152 * Create a new {@code ExceptionTree} object, to represent an {@code @exception } tag. 153 * @param name the name of the exception 154 * @param description a description of why the exception might be thrown 155 * @return an {@code ExceptionTree} object 156 */ 157 ThrowsTree newExceptionTree(ReferenceTree name, List<? extends DocTree> description); 158 159 /** 160 * Create a new {@code HiddenTree} object, to represent an {@code {@hidden } } tag. 161 * @param text the content of the tag 162 * @return a {@code HiddenTree} object 163 */ 164 HiddenTree newHiddenTree(List<? extends DocTree> text); 165 166 /** 167 * Create a new {@code IdentifierTree} object, to represent an identifier, such as in a 168 * {@code @param } tag. 169 * @param name the name of the identifier 170 * @return an {@code IdentifierTree} object 171 */ 172 IdentifierTree newIdentifierTree(Name name); 173 174 /** 175 * Create a new {@code IndexTree} object, to represent an {@code {@index } } tag. 176 * @param term the search term 177 * @param description an optional description of the search term 178 * @return an {@code IndexTree} object 179 */ 180 IndexTree newIndexTree(DocTree term, List<? extends DocTree> description); 181 182 /** 183 * Create a new {@code InheritDocTree} object, to represent an {@code {@inheritDoc} } tag. 184 * @return an {@code InheritDocTree} object 185 */ 186 InheritDocTree newInheritDocTree(); 187 188 /** 189 * Create a new {@code LinkTree} object, to represent a {@code {@link } } tag. 190 * @param ref the API element being referenced 191 * @param label an optional label for the link 192 * @return a {@code LinkTree} object 193 */ 194 LinkTree newLinkTree(ReferenceTree ref, List<? extends DocTree> label); 195 196 /** 197 * Create a new {@code LinkPlainTree} object, to represent a {@code {@linkplain } } tag. 198 * @param ref the API element being referenced 199 * @param label an optional label for the link 200 * @return a {@code LinkPlainTree} object 201 */ 202 LinkTree newLinkPlainTree(ReferenceTree ref, List<? extends DocTree> label); 203 204 /** 205 * Create a new {@code LiteralTree} object, to represent a {@code {@literal } } tag. 206 * @param text the content of the tag 207 * @return a {@code LiteralTree} object 208 */ 209 LiteralTree newLiteralTree(TextTree text); 210 211 /** 212 * Create a new {@code ParamTree} object, to represent a {@code @param } tag. 213 * @param isTypeParameter true if this is a type parameter, and false otherwise 214 * @param name the parameter being described 215 * @param description the description of the parameter 216 * @return a {@code ParamTree} object 217 */ 218 ParamTree newParamTree(boolean isTypeParameter, IdentifierTree name, List<? extends DocTree> description); 219 220 /** 221 * Create a new {@code ReferenceTree} object, to represent a reference to an API element. 222 * 223 * @param signature the doc comment signature of the reference 224 * @return a {@code ReferenceTree} object 225 */ 226 ReferenceTree newReferenceTree(String signature); 227 228 /** 229 * Create a new {@code ReturnTree} object, to represent a {@code @return } tag. 230 * @param description the description of the return value of a method 231 * @return a {@code ReturnTree} object 232 */ 233 ReturnTree newReturnTree(List<? extends DocTree> description); 234 235 /** 236 * Create a new {@code SeeTree} object, to represent a {@code @see } tag. 237 * @param reference the reference 238 * @return a {@code SeeTree} object 239 */ 240 SeeTree newSeeTree(List<? extends DocTree> reference); 241 242 /** 243 * Create a new {@code SerialTree} object, to represent a {@code @serial } tag. 244 * @param description the description for the tag 245 * @return a {@code SerialTree} object 246 */ 247 SerialTree newSerialTree(List<? extends DocTree> description); 248 249 /** 250 * Create a new {@code SerialDataTree} object, to represent a {@code @serialData } tag. 251 * @param description the description for the tag 252 * @return a {@code SerialDataTree} object 253 */ 254 SerialDataTree newSerialDataTree(List<? extends DocTree> description); 255 256 /** 257 * Create a new {@code SerialFieldTree} object, to represent a {@code @serialField } tag. 258 * @param name the name of the field 259 * @param type the type of the field 260 * @param description the description of the field 261 * @return a {@code SerialFieldTree} object 262 */ 263 SerialFieldTree newSerialFieldTree(IdentifierTree name, ReferenceTree type, List<? extends DocTree> description); 264 265 /** 266 * Create a new {@code SinceTree} object, to represent a {@code @since } tag. 267 * @param text the content of the tag 268 * @return a {@code SinceTree} object 269 */ 270 SinceTree newSinceTree(List<? extends DocTree> text); 271 272 /** 273 * Create a new {@code StartElementTree} object, to represent the start of an HTML element. 274 * @param name the name of the HTML element 275 * @param attrs the attributes 276 * @param selfClosing true if the start element is marked as self-closing; otherwise false 277 * @return a {@code StartElementTree} object 278 */ 279 StartElementTree newStartElementTree(Name name, List<? extends DocTree> attrs, boolean selfClosing); 280 281 /** 282 * Create a new {@code TextTree} object, to represent some plain text. 283 * @param text the text 284 * @return a {@code TextTree} object 285 */ 286 TextTree newTextTree(String text); 287 288 /** 289 * Create a new {@code ThrowsTree} object, to represent a {@code @throws } tag. 290 * @param name the name of the exception 291 * @param description a description of why the exception might be thrown 292 * @return a {@code ThrowsTree} object 293 */ 294 ThrowsTree newThrowsTree(ReferenceTree name, List<? extends DocTree> description); 295 296 /** 297 * Create a new {@code UnknownBlockTagTree} object, to represent an unrecognized block tag. 298 * @param name the name of the block tag 299 * @param content the content 300 * @return an {@code UnknownBlockTagTree} object 301 */ 302 UnknownBlockTagTree newUnknownBlockTagTree(Name name, List<? extends DocTree> content); 303 304 /** 305 * Create a new {@code UnknownInlineTagTree} object, to represent an unrecognized inline tag. 306 * @param name the name of the inline tag 307 * @param content the content 308 * @return an {@code UnknownInlineTagTree} object 309 */ 310 UnknownInlineTagTree newUnknownInlineTagTree(Name name, List<? extends DocTree> content); 311 312 /** 313 * Create a new {@code ValueTree} object, to represent a {@code {@value } } tag. 314 * @param ref a reference to the value 315 * @return a {@code ValueTree} object 316 */ 317 ValueTree newValueTree(ReferenceTree ref); 318 319 /** 320 * Create a new {@code VersionTree} object, to represent a {@code {@version } } tag. 321 * @param text the content of the tag 322 * @return a {@code VersionTree} object 323 */ 324 VersionTree newVersionTree(List<? extends DocTree> text); 325 326 /** 327 * Set the position to be recorded in subsequent tree nodes created by this factory. 328 * The position should be a character offset relative to the beginning of the source file 329 * or {@link javax.tools.Diagnostic#NOPOS NOPOS}. 330 * @param pos the position 331 * @return this object, to facilitate method chaining 332 */ 333 DocTreeFactory at(int pos); 334 335 /** 336 * Get the first sentence contained in a list of content. 337 * The determination of the first sentence is implementation specific, and may 338 * involve the use of a locale-specific {@link java.text.BreakIterator BreakIterator} 339 * and other heuristics. 340 * The resulting list may share a common set of initial items with the input list. 341 * @param list the list 342 * @return a list containing the first sentence of the list. 343 */ 344 List<DocTree> getFirstSentence(List<? extends DocTree> list); 345 346} 347