DocTreeFactory.java revision 3692:87b48a8fb3cf
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 fullBody the entire body of the doc comment 116 * @param tags the block tags in the doc comment 117 * @return a {@code DocCommentTree} object 118 */ 119 DocCommentTree newDocCommentTree(List<? extends DocTree> fullBody, 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 HiddenTree} object, to represent an {@code {@hidden } } tag. 160 * @param text the content of the tag 161 * @return a {@code HiddenTree} object 162 */ 163 HiddenTree newHiddenTree(List<? extends DocTree> text); 164 165 /** 166 * Create a new {@code IdentifierTree} object, to represent an identifier, such as in a 167 * {@code @param } tag. 168 * @param name the name of the identifier 169 * @return an {@code IdentifierTree} object 170 */ 171 IdentifierTree newIdentifierTree(Name name); 172 173 /** 174 * Create a new {@code IndexTree} object, to represent an {@code {@index } } tag. 175 * @param term the search term 176 * @param description an optional description of the search term 177 * @return an {@code IndexTree} object 178 */ 179 IndexTree newIndexTree(DocTree term, List<? extends DocTree> description); 180 181 /** 182 * Create a new {@code InheritDocTree} object, to represent an {@code {@inheritDoc} } tag. 183 * @return an {@code InheritDocTree} object 184 */ 185 InheritDocTree newInheritDocTree(); 186 187 /** 188 * Create a new {@code LinkTree} object, to represent a {@code {@link } } tag. 189 * @param ref the API element being referenced 190 * @param label an optional label for the link 191 * @return a {@code LinkTree} object 192 */ 193 LinkTree newLinkTree(ReferenceTree ref, List<? extends DocTree> label); 194 195 /** 196 * Create a new {@code LinkPlainTree} object, to represent a {@code {@linkplain } } tag. 197 * @param ref the API element being referenced 198 * @param label an optional label for the link 199 * @return a {@code LinkPlainTree} object 200 */ 201 LinkTree newLinkPlainTree(ReferenceTree ref, List<? extends DocTree> label); 202 203 /** 204 * Create a new {@code LiteralTree} object, to represent a {@code {@literal } } tag. 205 * @param text the content of the tag 206 * @return a {@code LiteralTree} object 207 */ 208 LiteralTree newLiteralTree(TextTree text); 209 210 /** 211 * Create a new {@code ParamTree} object, to represent a {@code @param } tag. 212 * @param isTypeParameter true if this is a type parameter, and false otherwise 213 * @param name the parameter being described 214 * @param description the description of the parameter 215 * @return a {@code ParamTree} object 216 */ 217 ParamTree newParamTree(boolean isTypeParameter, IdentifierTree name, List<? extends DocTree> description); 218 219 /** 220 * Create a new {@code ReferenceTree} object, to represent a reference to an API element. 221 * 222 * @param signature the doc comment signature of the reference 223 * @return a {@code ReferenceTree} object 224 */ 225 ReferenceTree newReferenceTree(String signature); 226 227 /** 228 * Create a new {@code ReturnTree} object, to represent a {@code @return } tag. 229 * @param description the description of the return value of a method 230 * @return a {@code ReturnTree} object 231 */ 232 ReturnTree newReturnTree(List<? extends DocTree> description); 233 234 /** 235 * Create a new {@code SeeTree} object, to represent a {@code @see } tag. 236 * @param reference the reference 237 * @return a {@code SeeTree} object 238 */ 239 SeeTree newSeeTree(List<? extends DocTree> reference); 240 241 /** 242 * Create a new {@code SerialTree} object, to represent a {@code @serial } tag. 243 * @param description the description for the tag 244 * @return a {@code SerialTree} object 245 */ 246 SerialTree newSerialTree(List<? extends DocTree> description); 247 248 /** 249 * Create a new {@code SerialDataTree} object, to represent a {@code @serialData } tag. 250 * @param description the description for the tag 251 * @return a {@code SerialDataTree} object 252 */ 253 SerialDataTree newSerialDataTree(List<? extends DocTree> description); 254 255 /** 256 * Create a new {@code SerialFieldTree} object, to represent a {@code @serialField } tag. 257 * @param name the name of the field 258 * @param type the type of the field 259 * @param description the description of the field 260 * @return a {@code SerialFieldTree} object 261 */ 262 SerialFieldTree newSerialFieldTree(IdentifierTree name, ReferenceTree type, List<? extends DocTree> description); 263 264 /** 265 * Create a new {@code SinceTree} object, to represent a {@code @since } tag. 266 * @param text the content of the tag 267 * @return a {@code SinceTree} object 268 */ 269 SinceTree newSinceTree(List<? extends DocTree> text); 270 271 /** 272 * Create a new {@code StartElementTree} object, to represent the start of an HTML element. 273 * @param name the name of the HTML element 274 * @param attrs the attributes 275 * @param selfClosing true if the start element is marked as self-closing; otherwise false 276 * @return a {@code StartElementTree} object 277 */ 278 StartElementTree newStartElementTree(Name name, List<? extends DocTree> attrs, boolean selfClosing); 279 280 /** 281 * Create a new {@code TextTree} object, to represent some plain text. 282 * @param text the text 283 * @return a {@code TextTree} object 284 */ 285 TextTree newTextTree(String text); 286 287 /** 288 * Create a new {@code ThrowsTree} object, to represent a {@code @throws } tag. 289 * @param name the name of the exception 290 * @param description a description of why the exception might be thrown 291 * @return a {@code ThrowsTree} object 292 */ 293 ThrowsTree newThrowsTree(ReferenceTree name, List<? extends DocTree> description); 294 295 /** 296 * Create a new {@code UnknownBlockTagTree} object, to represent an unrecognized block tag. 297 * @param name the name of the block tag 298 * @param content the content 299 * @return an {@code UnknownBlockTagTree} object 300 */ 301 UnknownBlockTagTree newUnknownBlockTagTree(Name name, List<? extends DocTree> content); 302 303 /** 304 * Create a new {@code UnknownInlineTagTree} object, to represent an unrecognized inline tag. 305 * @param name the name of the inline tag 306 * @param content the content 307 * @return an {@code UnknownInlineTagTree} object 308 */ 309 UnknownInlineTagTree newUnknownInlineTagTree(Name name, List<? extends DocTree> content); 310 311 /** 312 * Create a new {@code ValueTree} object, to represent a {@code {@value } } tag. 313 * @param ref a reference to the value 314 * @return a {@code ValueTree} object 315 */ 316 ValueTree newValueTree(ReferenceTree ref); 317 318 /** 319 * Create a new {@code VersionTree} object, to represent a {@code {@version } } tag. 320 * @param text the content of the tag 321 * @return a {@code VersionTree} object 322 */ 323 VersionTree newVersionTree(List<? extends DocTree> text); 324 325 /** 326 * Set the position to be recorded in subsequent tree nodes created by this factory. 327 * The position should be a character offset relative to the beginning of the source file 328 * or {@link javax.tools.Diagnostic#NOPOS NOPOS}. 329 * @param pos the position 330 * @return this object, to facilitate method chaining 331 */ 332 DocTreeFactory at(int pos); 333 334 /** 335 * Get the first sentence contained in a list of content. 336 * The determination of the first sentence is implementation specific, and may 337 * involve the use of a locale-specific {@link java.text.BreakIterator BreakIterator} 338 * and other heuristics. 339 * The resulting list may share a common set of initial items with the input list. 340 * @param list the list 341 * @return a list containing the first sentence of the list. 342 */ 343 List<DocTree> getFirstSentence(List<? extends DocTree> list); 344 345} 346