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