/*
* This file is a shadowed version of the older javadoc codebase on which gosudoc is based; borrowed from jdk 9.
*/
package gw.gosudoc.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.source.util.TreePath;
import gw.gosudoc.com.sun.javadoc.Tag;
import gw.gosudoc.com.sun.tools.doclets.internal.toolkit.util.FatalError;
import com.sun.tools.javac.tree.JCTree;
import com.sun.tools.javac.tree.JCTree.JCCompilationUnit;
import com.sun.tools.javac.util.Position;
import manifold.util.ReflectUtil;
/**
* 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.
*
* 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.
*
* @since 1.2
* @author Robert Field
* @author Atul M Dambalkar
* @author Neal Gafter (rewrite)
*/
@Deprecated
public abstract class DocImpl implements gw.gosudoc.com.sun.javadoc.Doc, Comparable {
/**
* 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 gw.gosudoc.com.sun.tools.javadoc.main.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 gw.gosudoc.com.sun.javadoc.Tag[] firstSentence;
/**
* Cached inline tags.
*/
private gw.gosudoc.com.sun.javadoc.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.
*/
gw.gosudoc.com.sun.tools.javadoc.main.Comment comment() {
if (comment == null) {
String d = documentation();
if (env.javaScriptScanner != null) {
env.javaScriptScanner.parse(d, new JavaScriptScanner.Reporter() {
@Override
public void report() {
env.error(DocImpl.this, "javadoc.JavaScript_in_comment");
throw new FatalError();
}
});
}
if (env.doclint != null
&& treePath != null
&& env.shouldCheck(treePath.getCompilationUnit())
&& d.equals(getCommentText(treePath))) {
ReflectUtil.method( env.doclint, "scan", TreePath.class ).invoke(treePath);
}
comment = new gw.gosudoc.com.sun.tools.javadoc.main.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 gw.gosudoc.com.sun.javadoc.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 gw.gosudoc.com.sun.javadoc.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 gw.gosudoc.com.sun.javadoc.SeeTag[] seeTags() {
return comment().seeTags();
}
public gw.gosudoc.com.sun.javadoc.Tag[] inlineTags() {
if (inlineTags == null) {
inlineTags = gw.gosudoc.com.sun.tools.javadoc.main.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 = gw.gosudoc.com.sun.tools.javadoc.main.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).*]*>(.*)
* 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.
*
* 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 gw.gosudoc.com.sun.javadoc.SourcePosition position() { return null; }
}
