Mercurial > jdk8-mips64-public > langtools / file revision
src/share/classes/com/sun/tools/javadoc/DocImpl.java@25e14ad23cef
src/share/classes/com/sun/tools/javadoc/DocImpl.java
Wed, 10 Oct 2012 16:48:21 -0700
- author
- jjg
- date
- Wed, 10 Oct 2012 16:48:21 -0700
- changeset 1359
- 25e14ad23cef
- parent 1358
- fc123bdeddb8
- child 1443
- cfde9737131e
- permissions
- -rw-r--r--
8000665: fix "internal API" comments on javadoc files
Reviewed-by: darcy
1 /*
2 * Copyright (c) 1997, 2012, 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 */
26 package com.sun.tools.javadoc;
28 import java.io.DataInputStream;
29 import java.io.IOException;
30 import java.io.InputStream;
31 import java.text.CollationKey;
32 import java.util.regex.Matcher;
33 import java.util.regex.Pattern;
35 import javax.tools.FileObject;
37 import com.sun.javadoc.*;
38 import com.sun.tools.javac.util.Position;
40 /**
41 * abstract base class of all Doc classes. Doc item's are representations
42 * of java language constructs (class, package, method,...) which have
43 * comments and have been processed by this run of javadoc. All Doc items
44 * are unique, that is, they are == comparable.
45 *
46 * <p><b>This is NOT part of any supported API.
47 * If you write code that depends on this, you do so at your own risk.
48 * This code and its internal interfaces are subject to change or
49 * deletion without notice.</b>
50 *
51 * @since 1.2
52 * @author Robert Field
53 * @author Atul M Dambalkar
54 * @author Neal Gafter (rewrite)
55 */
56 public abstract class DocImpl implements Doc, Comparable<Object> {
58 /**
59 * Doc environment
60 */
61 protected final DocEnv env; //### Rename this everywhere to 'docenv' ?
63 /**
64 * The complex comment object, lazily initialized.
65 */
66 private Comment comment;
68 /**
69 * The cached sort key, to take care of Natural Language Text sorting.
70 */
71 private CollationKey collationkey = null;
73 /**
74 * Raw documentation string.
75 */
76 protected String documentation; // Accessed in PackageDocImpl, RootDocImpl
78 /**
79 * Cached first sentence.
80 */
81 private Tag[] firstSentence;
83 /**
84 * Cached inline tags.
85 */
86 private Tag[] inlineTags;
88 /**
89 * Constructor.
90 */
91 DocImpl(DocEnv env, String documentation) {
92 this.documentation = documentation;
93 this.env = env;
94 }
96 /**
97 * So subclasses have the option to do lazy initialization of
98 * "documentation" string.
99 */
100 protected String documentation() {
101 if (documentation == null) documentation = "";
102 return documentation;
103 }
105 /**
106 * For lazy initialization of comment.
107 */
108 Comment comment() {
109 if (comment == null) {
110 comment = new Comment(this, documentation());
111 }
112 return comment;
113 }
115 /**
116 * Return the text of the comment for this doc item.
117 * TagImpls have been removed.
118 */
119 public String commentText() {
120 return comment().commentText();
121 }
123 /**
124 * Return all tags in this Doc item.
125 *
126 * @return an array of TagImpl containing all tags on this Doc item.
127 */
128 public Tag[] tags() {
129 return comment().tags();
130 }
132 /**
133 * Return tags of the specified kind in this Doc item.
134 *
135 * @param tagname name of the tag kind to search for.
136 * @return an array of TagImpl containing all tags whose 'kind()'
137 * matches 'tagname'.
138 */
139 public Tag[] tags(String tagname) {
140 return comment().tags(tagname);
141 }
143 /**
144 * Return the see also tags in this Doc item.
145 *
146 * @return an array of SeeTag containing all @see tags.
147 */
148 public SeeTag[] seeTags() {
149 return comment().seeTags();
150 }
152 public Tag[] inlineTags() {
153 if (inlineTags == null) {
154 inlineTags = Comment.getInlineTags(this, commentText());
155 }
156 return inlineTags;
157 }
159 public Tag[] firstSentenceTags() {
160 if (firstSentence == null) {
161 //Parse all sentences first to avoid duplicate warnings.
162 inlineTags();
163 try {
164 env.setSilent(true);
165 firstSentence = Comment.firstSentenceTags(this, commentText());
166 } finally {
167 env.setSilent(false);
168 }
169 }
170 return firstSentence;
171 }
173 /**
174 * Utility for subclasses which read HTML documentation files.
175 */
176 String readHTMLDocumentation(InputStream input, FileObject filename) throws IOException {
177 byte[] filecontents = new byte[input.available()];
178 try {
179 DataInputStream dataIn = new DataInputStream(input);
180 dataIn.readFully(filecontents);
181 } finally {
182 input.close();
183 }
184 String encoding = env.getEncoding();
185 String rawDoc = (encoding!=null)
186 ? new String(filecontents, encoding)
187 : new String(filecontents);
188 Pattern bodyPat = Pattern.compile("(?is).*<body\\b[^>]*>(.*)</body\\b.*");
189 Matcher m = bodyPat.matcher(rawDoc);
190 if (m.matches()) {
191 return m.group(1);
192 } else {
193 String key = rawDoc.matches("(?is).*<body\\b.*")
194 ? "javadoc.End_body_missing_from_html_file"
195 : "javadoc.Body_missing_from_html_file";
196 env.error(SourcePositionImpl.make(filename, Position.NOPOS, null), key);
197 return "";
198 }
199 }
201 /**
202 * Return the full unprocessed text of the comment. Tags
203 * are included as text. Used mainly for store and retrieve
204 * operations like internalization.
205 */
206 public String getRawCommentText() {
207 return documentation();
208 }
210 /**
211 * Set the full unprocessed text of the comment. Tags
212 * are included as text. Used mainly for store and retrieve
213 * operations like internalization.
214 */
215 public void setRawCommentText(String rawDocumentation) {
216 documentation = rawDocumentation;
217 comment = null;
218 }
220 /**
221 * return a key for sorting.
222 */
223 CollationKey key() {
224 if (collationkey == null) {
225 collationkey = generateKey();
226 }
227 return collationkey;
228 }
230 /**
231 * Generate a key for sorting.
232 * <p>
233 * Default is name().
234 */
235 CollationKey generateKey() {
236 String k = name();
237 // System.out.println("COLLATION KEY FOR " + this + " is \"" + k + "\"");
238 return env.doclocale.collator.getCollationKey(k);
239 }
241 /**
242 * Returns a string representation of this Doc item.
243 */
244 @Override
245 public String toString() {
246 return qualifiedName();
247 }
249 /**
250 * Returns the name of this Doc item.
251 *
252 * @return the name
253 */
254 public abstract String name();
256 /**
257 * Returns the qualified name of this Doc item.
258 *
259 * @return the name
260 */
261 public abstract String qualifiedName();
263 /**
264 * Compares this Object with the specified Object for order. Returns a
265 * negative integer, zero, or a positive integer as this Object is less
266 * than, equal to, or greater than the given Object.
267 * <p>
268 * Included so that Doc item are java.lang.Comparable.
269 *
270 * @param obj the {@code Object} to be compared.
271 * @return a negative integer, zero, or a positive integer as this Object
272 * is less than, equal to, or greater than the given Object.
273 * @exception ClassCastException the specified Object's type prevents it
274 * from being compared to this Object.
275 */
276 public int compareTo(Object obj) {
277 // System.out.println("COMPARE \"" + this + "\" to \"" + obj + "\" = " + key().compareTo(((DocImpl)obj).key()));
278 return key().compareTo(((DocImpl)obj).key());
279 }
281 /**
282 * Is this Doc item a field? False until overridden.
283 *
284 * @return true if it represents a field
285 */
286 public boolean isField() {
287 return false;
288 }
290 /**
291 * Is this Doc item an enum constant? False until overridden.
292 *
293 * @return true if it represents an enum constant
294 */
295 public boolean isEnumConstant() {
296 return false;
297 }
299 /**
300 * Is this Doc item a constructor? False until overridden.
301 *
302 * @return true if it represents a constructor
303 */
304 public boolean isConstructor() {
305 return false;
306 }
308 /**
309 * Is this Doc item a method (but not a constructor or annotation
310 * type element)?
311 * False until overridden.
312 *
313 * @return true if it represents a method
314 */
315 public boolean isMethod() {
316 return false;
317 }
319 /**
320 * Is this Doc item an annotation type element?
321 * False until overridden.
322 *
323 * @return true if it represents an annotation type element
324 */
325 public boolean isAnnotationTypeElement() {
326 return false;
327 }
329 /**
330 * Is this Doc item a interface (but not an annotation type)?
331 * False until overridden.
332 *
333 * @return true if it represents a interface
334 */
335 public boolean isInterface() {
336 return false;
337 }
339 /**
340 * Is this Doc item a exception class? False until overridden.
341 *
342 * @return true if it represents a exception
343 */
344 public boolean isException() {
345 return false;
346 }
348 /**
349 * Is this Doc item a error class? False until overridden.
350 *
351 * @return true if it represents a error
352 */
353 public boolean isError() {
354 return false;
355 }
357 /**
358 * Is this Doc item an enum type? False until overridden.
359 *
360 * @return true if it represents an enum type
361 */
362 public boolean isEnum() {
363 return false;
364 }
366 /**
367 * Is this Doc item an annotation type? False until overridden.
368 *
369 * @return true if it represents an annotation type
370 */
371 public boolean isAnnotationType() {
372 return false;
373 }
375 /**
376 * Is this Doc item an ordinary class (i.e. not an interface,
377 * annotation type, enumeration, exception, or error)?
378 * False until overridden.
379 *
380 * @return true if it represents an ordinary class
381 */
382 public boolean isOrdinaryClass() {
383 return false;
384 }
386 /**
387 * Is this Doc item a class
388 * (and not an interface or annotation type)?
389 * This includes ordinary classes, enums, errors and exceptions.
390 * False until overridden.
391 *
392 * @return true if it represents a class
393 */
394 public boolean isClass() {
395 return false;
396 }
398 /**
399 * return true if this Doc is include in the active set.
400 */
401 public abstract boolean isIncluded();
403 /**
404 * Return the source position of the entity, or null if
405 * no position is available.
406 */
407 public SourcePosition position() { return null; }
408 }
