0N/A/*
910N/A * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0N/A *
0N/A * This code is free software; you can redistribute it and/or modify it
0N/A * under the terms of the GNU General Public License version 2 only, as
553N/A * published by the Free Software Foundation. Oracle designates this
0N/A * particular file as subject to the "Classpath" exception as provided
553N/A * by Oracle in the LICENSE file that accompanied this code.
0N/A *
0N/A * This code is distributed in the hope that it will be useful, but WITHOUT
0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0N/A * version 2 for more details (a copy is included in the LICENSE file that
0N/A * accompanied this code).
0N/A *
0N/A * You should have received a copy of the GNU General Public License version
0N/A * 2 along with this work; if not, write to the Free Software Foundation,
0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0N/A *
553N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
553N/A * or visit www.oracle.com if you need additional information or have any
553N/A * questions.
0N/A */
0N/A
0N/Apackage com.sun.tools.javadoc;
0N/A
910N/Aimport java.io.DataInputStream;
0N/Aimport java.io.InputStream;
0N/Aimport java.io.IOException;
0N/Aimport java.text.CollationKey;
196N/Aimport javax.tools.FileObject;
196N/A
196N/Aimport com.sun.javadoc.*;
196N/A
0N/Aimport com.sun.tools.javac.util.Position;
910N/Aimport java.util.regex.Matcher;
910N/Aimport java.util.regex.Pattern;
0N/A
0N/A/**
0N/A * abstract base class of all Doc classes. Doc item's are representations
0N/A * of java language constructs (class, package, method,...) which have
0N/A * comments and have been processed by this run of javadoc. All Doc items
0N/A * are unique, that is, they are == comparable.
0N/A *
0N/A * @since 1.2
0N/A * @author Robert Field
0N/A * @author Atul M Dambalkar
0N/A * @author Neal Gafter (rewrite)
0N/A */
196N/Apublic abstract class DocImpl implements Doc, Comparable<Object> {
0N/A
0N/A /**
0N/A * Doc environment
0N/A */
0N/A protected final DocEnv env; //### Rename this everywhere to 'docenv' ?
0N/A
0N/A /**
0N/A * The complex comment object, lazily initialized.
0N/A */
0N/A private Comment comment;
0N/A
0N/A /**
0N/A * The cached sort key, to take care of Natural Language Text sorting.
0N/A */
0N/A private CollationKey collationkey = null;
0N/A
0N/A /**
0N/A * Raw documentation string.
0N/A */
0N/A protected String documentation; // Accessed in PackageDocImpl, RootDocImpl
0N/A
0N/A /**
0N/A * Cached first sentence.
0N/A */
0N/A private Tag[] firstSentence;
0N/A
0N/A /**
0N/A * Cached inline tags.
0N/A */
0N/A private Tag[] inlineTags;
0N/A
0N/A /**
0N/A * Constructor.
0N/A */
0N/A DocImpl(DocEnv env, String documentation) {
0N/A this.documentation = documentation;
0N/A this.env = env;
0N/A }
0N/A
0N/A /**
0N/A * So subclasses have the option to do lazy initialization of
0N/A * "documentation" string.
0N/A */
1043N/A protected String documentation() {
0N/A if (documentation == null) documentation = "";
0N/A return documentation;
0N/A }
0N/A
0N/A /**
0N/A * For lazy initialization of comment.
0N/A */
0N/A Comment comment() {
0N/A if (comment == null) {
0N/A comment = new Comment(this, documentation());
0N/A }
0N/A return comment;
0N/A }
0N/A
0N/A /**
0N/A * Return the text of the comment for this doc item.
0N/A * TagImpls have been removed.
0N/A */
0N/A public String commentText() {
0N/A return comment().commentText();
0N/A }
0N/A
0N/A /**
0N/A * Return all tags in this Doc item.
0N/A *
0N/A * @return an array of TagImpl containing all tags on this Doc item.
0N/A */
0N/A public Tag[] tags() {
0N/A return comment().tags();
0N/A }
0N/A
0N/A /**
0N/A * Return tags of the specified kind in this Doc item.
0N/A *
0N/A * @param tagname name of the tag kind to search for.
0N/A * @return an array of TagImpl containing all tags whose 'kind()'
0N/A * matches 'tagname'.
0N/A */
0N/A public Tag[] tags(String tagname) {
0N/A return comment().tags(tagname);
0N/A }
0N/A
0N/A /**
0N/A * Return the see also tags in this Doc item.
0N/A *
0N/A * @return an array of SeeTag containing all &#64see tags.
0N/A */
0N/A public SeeTag[] seeTags() {
0N/A return comment().seeTags();
0N/A }
0N/A
0N/A public Tag[] inlineTags() {
0N/A if (inlineTags == null) {
0N/A inlineTags = Comment.getInlineTags(this, commentText());
0N/A }
0N/A return inlineTags;
0N/A }
0N/A
0N/A public Tag[] firstSentenceTags() {
0N/A if (firstSentence == null) {
0N/A //Parse all sentences first to avoid duplicate warnings.
0N/A inlineTags();
0N/A try {
0N/A env.setSilent(true);
0N/A firstSentence = Comment.firstSentenceTags(this, commentText());
0N/A } finally {
0N/A env.setSilent(false);
0N/A }
0N/A }
0N/A return firstSentence;
0N/A }
0N/A
0N/A /**
0N/A * Utility for subclasses which read HTML documentation files.
0N/A */
196N/A String readHTMLDocumentation(InputStream input, FileObject filename) throws IOException {
910N/A byte[] filecontents = new byte[input.available()];
910N/A try {
910N/A DataInputStream dataIn = new DataInputStream(input);
910N/A dataIn.readFully(filecontents);
910N/A } finally {
910N/A input.close();
910N/A }
0N/A String encoding = env.getEncoding();
0N/A String rawDoc = (encoding!=null)
0N/A ? new String(filecontents, encoding)
0N/A : new String(filecontents);
910N/A Pattern bodyPat = Pattern.compile("(?is).*<body\\b[^>]*>(.*)</body\\b.*");
910N/A Matcher m = bodyPat.matcher(rawDoc);
910N/A if (m.matches()) {
910N/A return m.group(1);
910N/A } else {
910N/A String key = rawDoc.matches("(?is).*<body\\b.*")
910N/A ? "javadoc.End_body_missing_from_html_file"
910N/A : "javadoc.Body_missing_from_html_file";
910N/A env.error(SourcePositionImpl.make(filename, Position.NOPOS, null), key);
0N/A return "";
0N/A }
0N/A }
0N/A
0N/A /**
0N/A * Return the full unprocessed text of the comment. Tags
0N/A * are included as text. Used mainly for store and retrieve
0N/A * operations like internalization.
0N/A */
0N/A public String getRawCommentText() {
0N/A return documentation();
0N/A }
0N/A
0N/A /**
0N/A * Set the full unprocessed text of the comment. Tags
0N/A * are included as text. Used mainly for store and retrieve
0N/A * operations like internalization.
0N/A */
0N/A public void setRawCommentText(String rawDocumentation) {
0N/A documentation = rawDocumentation;
0N/A comment = null;
0N/A }
0N/A
0N/A /**
0N/A * return a key for sorting.
0N/A */
0N/A CollationKey key() {
0N/A if (collationkey == null) {
0N/A collationkey = generateKey();
0N/A }
0N/A return collationkey;
0N/A }
0N/A
0N/A /**
0N/A * Generate a key for sorting.
0N/A * <p>
0N/A * Default is name().
0N/A */
0N/A CollationKey generateKey() {
0N/A String k = name();
0N/A // System.out.println("COLLATION KEY FOR " + this + " is \"" + k + "\"");
0N/A return env.doclocale.collator.getCollationKey(k);
0N/A }
0N/A
0N/A /**
0N/A * Returns a string representation of this Doc item.
0N/A */
910N/A @Override
0N/A public String toString() {
0N/A return qualifiedName();
0N/A }
0N/A
0N/A /**
0N/A * Returns the name of this Doc item.
0N/A *
0N/A * @return the name
0N/A */
0N/A public abstract String name();
0N/A
0N/A /**
0N/A * Returns the qualified name of this Doc item.
0N/A *
0N/A * @return the name
0N/A */
0N/A public abstract String qualifiedName();
0N/A
0N/A /**
0N/A * Compares this Object with the specified Object for order. Returns a
0N/A * negative integer, zero, or a positive integer as this Object is less
0N/A * than, equal to, or greater than the given Object.
0N/A * <p>
0N/A * Included so that Doc item are java.lang.Comparable.
0N/A *
0N/A * @param o the <code>Object</code> to be compared.
0N/A * @return a negative integer, zero, or a positive integer as this Object
0N/A * is less than, equal to, or greater than the given Object.
0N/A * @exception ClassCastException the specified Object's type prevents it
0N/A * from being compared to this Object.
0N/A */
0N/A public int compareTo(Object obj) {
0N/A // System.out.println("COMPARE \"" + this + "\" to \"" + obj + "\" = " + key().compareTo(((DocImpl)obj).key()));
0N/A return key().compareTo(((DocImpl)obj).key());
0N/A }
0N/A
0N/A /**
0N/A * Is this Doc item a field? False until overridden.
0N/A *
0N/A * @return true if it represents a field
0N/A */
0N/A public boolean isField() {
0N/A return false;
0N/A }
0N/A
0N/A /**
0N/A * Is this Doc item an enum constant? False until overridden.
0N/A *
0N/A * @return true if it represents an enum constant
0N/A */
0N/A public boolean isEnumConstant() {
0N/A return false;
0N/A }
0N/A
0N/A /**
0N/A * Is this Doc item a constructor? False until overridden.
0N/A *
0N/A * @return true if it represents a constructor
0N/A */
0N/A public boolean isConstructor() {
0N/A return false;
0N/A }
0N/A
0N/A /**
0N/A * Is this Doc item a method (but not a constructor or annotation
0N/A * type element)?
0N/A * False until overridden.
0N/A *
0N/A * @return true if it represents a method
0N/A */
0N/A public boolean isMethod() {
0N/A return false;
0N/A }
0N/A
0N/A /**
0N/A * Is this Doc item an annotation type element?
0N/A * False until overridden.
0N/A *
0N/A * @return true if it represents an annotation type element
0N/A */
0N/A public boolean isAnnotationTypeElement() {
0N/A return false;
0N/A }
0N/A
0N/A /**
0N/A * Is this Doc item a interface (but not an annotation type)?
0N/A * False until overridden.
0N/A *
0N/A * @return true if it represents a interface
0N/A */
0N/A public boolean isInterface() {
0N/A return false;
0N/A }
0N/A
0N/A /**
0N/A * Is this Doc item a exception class? False until overridden.
0N/A *
0N/A * @return true if it represents a exception
0N/A */
0N/A public boolean isException() {
0N/A return false;
0N/A }
0N/A
0N/A /**
0N/A * Is this Doc item a error class? False until overridden.
0N/A *
0N/A * @return true if it represents a error
0N/A */
0N/A public boolean isError() {
0N/A return false;
0N/A }
0N/A
0N/A /**
0N/A * Is this Doc item an enum type? False until overridden.
0N/A *
0N/A * @return true if it represents an enum type
0N/A */
0N/A public boolean isEnum() {
0N/A return false;
0N/A }
0N/A
0N/A /**
0N/A * Is this Doc item an annotation type? False until overridden.
0N/A *
0N/A * @return true if it represents an annotation type
0N/A */
0N/A public boolean isAnnotationType() {
0N/A return false;
0N/A }
0N/A
0N/A /**
0N/A * Is this Doc item an ordinary class (i.e. not an interface,
0N/A * annotation type, enumeration, exception, or error)?
0N/A * False until overridden.
0N/A *
0N/A * @return true if it represents an ordinary class
0N/A */
0N/A public boolean isOrdinaryClass() {
0N/A return false;
0N/A }
0N/A
0N/A /**
0N/A * Is this Doc item a class
0N/A * (and not an interface or annotation type)?
0N/A * This includes ordinary classes, enums, errors and exceptions.
0N/A * False until overridden.
0N/A *
0N/A * @return true if it represents a class
0N/A */
0N/A public boolean isClass() {
0N/A return false;
0N/A }
0N/A
0N/A /**
0N/A * return true if this Doc is include in the active set.
0N/A */
0N/A public abstract boolean isIncluded();
0N/A
0N/A /**
0N/A * Return the source position of the entity, or null if
0N/A * no position is available.
0N/A */
0N/A public SourcePosition position() { return null; }
0N/A}