jdk8-mips64-public/langtools: src/share/classes/com/sun/tools/javadoc/DocEnv.java@60caf53b98e2 (annotated)

src/share/classes/com/sun/tools/javadoc/DocEnv.java@60caf53b98e2 (annotated)

src/share/classes/com/sun/tools/javadoc/DocEnv.java

Fri, 08 Feb 2013 17:35:16 -0800

author: jjg
date: Fri, 08 Feb 2013 17:35:16 -0800
changeset 1558: 60caf53b98e2
parent 1490: fc4cb1577ad6
child 1668: 991f11e13598
permissions: -rw-r--r--

8007610: javadoc doclint does not work with -private
Reviewed-by: darcy

 /*
  * Copyright (c) 2000, 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;
 import java.lang.reflect.Modifier;
 import java.util.*;
 import javax.tools.JavaFileManager;
 import com.sun.javadoc.*;
 import com.sun.source.util.JavacTask;
 import com.sun.source.util.TreePath;
 import com.sun.tools.doclint.DocLint;
 import com.sun.tools.javac.api.BasicJavacTask;
 import com.sun.tools.javac.code.*;
 import com.sun.tools.javac.code.Symbol.*;
 import com.sun.tools.javac.code.Type.ClassType;
 import com.sun.tools.javac.comp.Check;
 import com.sun.tools.javac.tree.JCTree;
 import com.sun.tools.javac.tree.JCTree.*;
 import com.sun.tools.javac.util.Context;
 import com.sun.tools.javac.util.Names;
 /**
  * Holds the environment for a run of javadoc.
  * Holds only the information needed throughout the
  * run and not the compiler info that could be GC'ed
  * or ported.
  *
  *  <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.4
  * @author Robert Field
  * @author Neal Gafter (rewrite)
  * @author Scott Seligman (generics)
  */
 public class DocEnv {
     protected static final Context.Key<DocEnv> docEnvKey =
         new Context.Key<DocEnv>();
     public static DocEnv instance(Context context) {
         DocEnv instance = context.get(docEnvKey);
         if (instance == null)
             instance = new DocEnv(context);
         return instance;
     }
     private Messager messager;
     DocLocale doclocale;
     /** Predefined symbols known to the compiler. */
     Symtab syms;
     /** Referenced directly in RootDocImpl. */
     JavadocClassReader reader;
     /** Javadoc's own version of the compiler's enter phase. */
     JavadocEnter enter;
     /** The name table. */
     Names names;
     /** The encoding name. */
     private String encoding;
     final Symbol externalizableSym;
     /** Access filter (public, protected, ...).  */
     protected ModifierFilter showAccess;
     /** True if we are using a sentence BreakIterator. */
     boolean breakiterator;
     /**
      * True if we do not want to print any notifications at all.
      */
     boolean quiet = false;
     Check chk;
     Types types;
     JavaFileManager fileManager;
     Context context;
     DocLint doclint;
     WeakHashMap<JCTree, TreePath> treePaths = new WeakHashMap<JCTree, TreePath>();
     /** Allow documenting from class files? */
     boolean docClasses = false;
     /** Does the doclet only expect pre-1.5 doclet API? */
     protected boolean legacyDoclet = true;
     /**
      * Set this to true if you would like to not emit any errors, warnings and
      * notices.
      */
     private boolean silent = false;
     /**
      * Constructor
      *
      * @param context      Context for this javadoc instance.
      */
     protected DocEnv(Context context) {
         context.put(docEnvKey, this);
         this.context = context;
         messager = Messager.instance0(context);
         syms = Symtab.instance(context);
         reader = JavadocClassReader.instance0(context);
         enter = JavadocEnter.instance0(context);
         names = Names.instance(context);
         externalizableSym = reader.enterClass(names.fromString("java.io.Externalizable"));
         chk = Check.instance(context);
         types = Types.instance(context);
         fileManager = context.get(JavaFileManager.class);
         // Default.  Should normally be reset with setLocale.
         this.doclocale = new DocLocale(this, "", breakiterator);
     }
     public void setSilent(boolean silent) {
         this.silent = silent;
     }
     /**
      * Look up ClassDoc by qualified name.
      */
     public ClassDocImpl lookupClass(String name) {
         ClassSymbol c = getClassSymbol(name);
         if (c != null) {
             return getClassDoc(c);
         } else {
             return null;
         }
     }
     /**
      * Load ClassDoc by qualified name.
      */
     public ClassDocImpl loadClass(String name) {
         try {
             ClassSymbol c = reader.loadClass(names.fromString(name));
             return getClassDoc(c);
         } catch (CompletionFailure ex) {
             chk.completionError(null, ex);
             return null;
         }
     }
     /**
      * Look up PackageDoc by qualified name.
      */
     public PackageDocImpl lookupPackage(String name) {
         //### Jing alleges that class check is needed
         //### to avoid a compiler bug.  Most likely
         //### instead a dummy created for error recovery.
         //### Should investigate this.
         PackageSymbol p = syms.packages.get(names.fromString(name));
         ClassSymbol c = getClassSymbol(name);
         if (p != null && c == null) {
             return getPackageDoc(p);
         } else {
             return null;
         }
     }
         // where
         /** Retrieve class symbol by fully-qualified name.
          */
         ClassSymbol getClassSymbol(String name) {
             // Name may contain nested class qualification.
             // Generate candidate flatnames with successively shorter
             // package qualifiers and longer nested class qualifiers.
             int nameLen = name.length();
             char[] nameChars = name.toCharArray();
             int idx = name.length();
             for (;;) {
                 ClassSymbol s = syms.classes.get(names.fromChars(nameChars, 0, nameLen));
                 if (s != null)
                     return s; // found it!
                 idx = name.substring(0, idx).lastIndexOf('.');
                 if (idx < 0) break;
                 nameChars[idx] = '$';
             }
             return null;
         }
     /**
      * Set the locale.
      */
     public void setLocale(String localeName) {
         // create locale specifics
         doclocale = new DocLocale(this, localeName, breakiterator);
         // update Messager if locale has changed.
         messager.setLocale(doclocale.locale);
     }
     /** Check whether this member should be documented. */
     public boolean shouldDocument(VarSymbol sym) {
         long mod = sym.flags();
         if ((mod & Flags.SYNTHETIC) != 0) {
             return false;
         }
         return showAccess.checkModifier(translateModifiers(mod));
     }
     /** Check whether this member should be documented. */
     public boolean shouldDocument(MethodSymbol sym) {
         long mod = sym.flags();
         if ((mod & Flags.SYNTHETIC) != 0) {
             return false;
         }
         return showAccess.checkModifier(translateModifiers(mod));
     }
     /** check whether this class should be documented. */
     public boolean shouldDocument(ClassSymbol sym) {
         return
             (sym.flags_field&Flags.SYNTHETIC) == 0 && // no synthetics
             (docClasses || getClassDoc(sym).tree != null) &&
             isVisible(sym);
     }
     //### Comment below is inaccurate wrt modifier filter testing
     /**
      * Check the visibility if this is an nested class.
      * if this is not a nested class, return true.
      * if this is an static visible nested class,
      *    return true.
      * if this is an visible nested class
      *    if the outer class is visible return true.
      *    else return false.
      * IMPORTANT: This also allows, static nested classes
      * to be defined inside an nested class, which is not
      * allowed by the compiler. So such an test case will
      * not reach upto this method itself, but if compiler
      * allows it, then that will go through.
      */
     protected boolean isVisible(ClassSymbol sym) {
         long mod = sym.flags_field;
         if (!showAccess.checkModifier(translateModifiers(mod))) {
             return false;
         }
         ClassSymbol encl = sym.owner.enclClass();
         return (encl == null || (mod & Flags.STATIC) != 0 || isVisible(encl));
     }
     //---------------- print forwarders ----------------//
     /**
      * Print error message, increment error count.
      *
      * @param msg message to print.
      */
     public void printError(String msg) {
         if (silent)
             return;
         messager.printError(msg);
     }
     /**
      * Print error message, increment error count.
      *
      * @param key selects message from resource
      */
     public void error(DocImpl doc, String key) {
         if (silent)
             return;
         messager.error(doc==null ? null : doc.position(), key);
     }
     /**
      * Print error message, increment error count.
      *
      * @param key selects message from resource
      */
     public void error(SourcePosition pos, String key) {
         if (silent)
             return;
         messager.error(pos, key);
     }
     /**
      * Print error message, increment error count.
      *
      * @param msg message to print.
      */
     public void printError(SourcePosition pos, String msg) {
         if (silent)
             return;
         messager.printError(pos, msg);
     }
     /**
      * Print error message, increment error count.
      *
      * @param key selects message from resource
      * @param a1 first argument
      */
     public void error(DocImpl doc, String key, String a1) {
         if (silent)
             return;
         messager.error(doc==null ? null : doc.position(), key, a1);
     }
     /**
      * Print error message, increment error count.
      *
      * @param key selects message from resource
      * @param a1 first argument
      * @param a2 second argument
      */
     public void error(DocImpl doc, String key, String a1, String a2) {
         if (silent)
             return;
         messager.error(doc==null ? null : doc.position(), key, a1, a2);
     }
     /**
      * Print error message, increment error count.
      *
      * @param key selects message from resource
      * @param a1 first argument
      * @param a2 second argument
      * @param a3 third argument
      */
     public void error(DocImpl doc, String key, String a1, String a2, String a3) {
         if (silent)
             return;
         messager.error(doc==null ? null : doc.position(), key, a1, a2, a3);
     }
     /**
      * Print warning message, increment warning count.
      *
      * @param msg message to print.
      */
     public void printWarning(String msg) {
         if (silent)
             return;
         messager.printWarning(msg);
     }
     /**
      * Print warning message, increment warning count.
      *
      * @param key selects message from resource
      */
     public void warning(DocImpl doc, String key) {
         if (silent)
             return;
         messager.warning(doc==null ? null : doc.position(), key);
     }
     /**
      * Print warning message, increment warning count.
      *
      * @param msg message to print.
      */
     public void printWarning(SourcePosition pos, String msg) {
         if (silent)
             return;
         messager.printWarning(pos, msg);
     }
     /**
      * Print warning message, increment warning count.
      *
      * @param key selects message from resource
      * @param a1 first argument
      */
     public void warning(DocImpl doc, String key, String a1) {
         if (silent)
             return;
         // suppress messages that have (probably) been covered by doclint
         if (doclint != null && doc != null && key.startsWith("tag"))
             return;
         messager.warning(doc==null ? null : doc.position(), key, a1);
     }
     /**
      * Print warning message, increment warning count.
      *
      * @param key selects message from resource
      * @param a1 first argument
      * @param a2 second argument
      */
     public void warning(DocImpl doc, String key, String a1, String a2) {
         if (silent)
             return;
         messager.warning(doc==null ? null : doc.position(), key, a1, a2);
     }
     /**
      * Print warning message, increment warning count.
      *
      * @param key selects message from resource
      * @param a1 first argument
      * @param a2 second argument
      * @param a3 third argument
      */
     public void warning(DocImpl doc, String key, String a1, String a2, String a3) {
         if (silent)
             return;
         messager.warning(doc==null ? null : doc.position(), key, a1, a2, a3);
     }
     /**
      * Print warning message, increment warning count.
      *
      * @param key selects message from resource
      * @param a1 first argument
      * @param a2 second argument
      * @param a3 third argument
      */
     public void warning(DocImpl doc, String key, String a1, String a2, String a3,
                         String a4) {
         if (silent)
             return;
         messager.warning(doc==null ? null : doc.position(), key, a1, a2, a3, a4);
     }
     /**
      * Print a message.
      *
      * @param msg message to print.
      */
     public void printNotice(String msg) {
         if (silent || quiet)
             return;
         messager.printNotice(msg);
     }
     /**
      * Print a message.
      *
      * @param key selects message from resource
      */
     public void notice(String key) {
         if (silent || quiet)
             return;
         messager.notice(key);
     }
     /**
      * Print a message.
      *
      * @param msg message to print.
      */
     public void printNotice(SourcePosition pos, String msg) {
         if (silent || quiet)
             return;
         messager.printNotice(pos, msg);
     }
     /**
      * Print a message.
      *
      * @param key selects message from resource
      * @param a1 first argument
      */
     public void notice(String key, String a1) {
         if (silent || quiet)
             return;
         messager.notice(key, a1);
     }
     /**
      * Print a message.
      *
      * @param key selects message from resource
      * @param a1 first argument
      * @param a2 second argument
      */
     public void notice(String key, String a1, String a2) {
         if (silent || quiet)
             return;
         messager.notice(key, a1, a2);
     }
     /**
      * Print a message.
      *
      * @param key selects message from resource
      * @param a1 first argument
      * @param a2 second argument
      * @param a3 third argument
      */
     public void notice(String key, String a1, String a2, String a3) {
         if (silent || quiet)
             return;
         messager.notice(key, a1, a2, a3);
     }
     /**
      * Exit, reporting errors and warnings.
      */
     public void exit() {
         // Messager should be replaced by a more general
         // compilation environment.  This can probably
         // subsume DocEnv as well.
         messager.exit();
     }
     protected Map<PackageSymbol, PackageDocImpl> packageMap =
             new HashMap<PackageSymbol, PackageDocImpl>();
     /**
      * Return the PackageDoc of this package symbol.
      */
     public PackageDocImpl getPackageDoc(PackageSymbol pack) {
         PackageDocImpl result = packageMap.get(pack);
         if (result != null) return result;
         result = new PackageDocImpl(this, pack);
         packageMap.put(pack, result);
         return result;
     }
     /**
      * Create the PackageDoc (or a subtype) for a package symbol.
      */
     void makePackageDoc(PackageSymbol pack, TreePath treePath) {
         PackageDocImpl result = packageMap.get(pack);
         if (result != null) {
             if (treePath != null) result.setTreePath(treePath);
         } else {
             result = new PackageDocImpl(this, pack, treePath);
             packageMap.put(pack, result);
         }
     }
     protected Map<ClassSymbol, ClassDocImpl> classMap =
             new HashMap<ClassSymbol, ClassDocImpl>();
     /**
      * Return the ClassDoc (or a subtype) of this class symbol.
      */
     public ClassDocImpl getClassDoc(ClassSymbol clazz) {
         ClassDocImpl result = classMap.get(clazz);
         if (result != null) return result;
         if (isAnnotationType(clazz)) {
             result = new AnnotationTypeDocImpl(this, clazz);
         } else {
             result = new ClassDocImpl(this, clazz);
         }
         classMap.put(clazz, result);
         return result;
     }
     /**
      * Create the ClassDoc (or a subtype) for a class symbol.
      */
     protected void makeClassDoc(ClassSymbol clazz, TreePath treePath) {
         ClassDocImpl result = classMap.get(clazz);
         if (result != null) {
             if (treePath != null) result.setTreePath(treePath);
             return;
         }
         if (isAnnotationType((JCClassDecl) treePath.getLeaf())) {   // flags of clazz may not yet be set
             result = new AnnotationTypeDocImpl(this, clazz, treePath);
         } else {
             result = new ClassDocImpl(this, clazz, treePath);
         }
         classMap.put(clazz, result);
     }
     protected static boolean isAnnotationType(ClassSymbol clazz) {
         return ClassDocImpl.isAnnotationType(clazz);
     }
     protected static boolean isAnnotationType(JCClassDecl tree) {
         return (tree.mods.flags & Flags.ANNOTATION) != 0;
     }
     protected Map<VarSymbol, FieldDocImpl> fieldMap =
             new HashMap<VarSymbol, FieldDocImpl>();
     /**
      * Return the FieldDoc of this var symbol.
      */
     public FieldDocImpl getFieldDoc(VarSymbol var) {
         FieldDocImpl result = fieldMap.get(var);
         if (result != null) return result;
         result = new FieldDocImpl(this, var);
         fieldMap.put(var, result);
         return result;
     }
     /**
      * Create a FieldDoc for a var symbol.
      */
     protected void makeFieldDoc(VarSymbol var, TreePath treePath) {
         FieldDocImpl result = fieldMap.get(var);
         if (result != null) {
             if (treePath != null) result.setTreePath(treePath);
         } else {
             result = new FieldDocImpl(this, var, treePath);
             fieldMap.put(var, result);
         }
     }
     protected Map<MethodSymbol, ExecutableMemberDocImpl> methodMap =
             new HashMap<MethodSymbol, ExecutableMemberDocImpl>();
     /**
      * Create a MethodDoc for this MethodSymbol.
      * Should be called only on symbols representing methods.
      */
     protected void makeMethodDoc(MethodSymbol meth, TreePath treePath) {
         MethodDocImpl result = (MethodDocImpl)methodMap.get(meth);
         if (result != null) {
             if (treePath != null) result.setTreePath(treePath);
         } else {
             result = new MethodDocImpl(this, meth, treePath);
             methodMap.put(meth, result);
         }
     }
     /**
      * Return the MethodDoc for a MethodSymbol.
      * Should be called only on symbols representing methods.
      */
     public MethodDocImpl getMethodDoc(MethodSymbol meth) {
         assert !meth.isConstructor() : "not expecting a constructor symbol";
         MethodDocImpl result = (MethodDocImpl)methodMap.get(meth);
         if (result != null) return result;
         result = new MethodDocImpl(this, meth);
         methodMap.put(meth, result);
         return result;
     }
     /**
      * Create the ConstructorDoc for a MethodSymbol.
      * Should be called only on symbols representing constructors.
      */
     protected void makeConstructorDoc(MethodSymbol meth, TreePath treePath) {
         ConstructorDocImpl result = (ConstructorDocImpl)methodMap.get(meth);
         if (result != null) {
             if (treePath != null) result.setTreePath(treePath);
         } else {
             result = new ConstructorDocImpl(this, meth, treePath);
             methodMap.put(meth, result);
         }
     }
     /**
      * Return the ConstructorDoc for a MethodSymbol.
      * Should be called only on symbols representing constructors.
      */
     public ConstructorDocImpl getConstructorDoc(MethodSymbol meth) {
         assert meth.isConstructor() : "expecting a constructor symbol";
         ConstructorDocImpl result = (ConstructorDocImpl)methodMap.get(meth);
         if (result != null) return result;
         result = new ConstructorDocImpl(this, meth);
         methodMap.put(meth, result);
         return result;
     }
     /**
      * Create the AnnotationTypeElementDoc for a MethodSymbol.
      * Should be called only on symbols representing annotation type elements.
      */
     protected void makeAnnotationTypeElementDoc(MethodSymbol meth, TreePath treePath) {
         AnnotationTypeElementDocImpl result =
             (AnnotationTypeElementDocImpl)methodMap.get(meth);
         if (result != null) {
             if (treePath != null) result.setTreePath(treePath);
         } else {
             result =
                 new AnnotationTypeElementDocImpl(this, meth, treePath);
             methodMap.put(meth, result);
         }
     }
     /**
      * Return the AnnotationTypeElementDoc for a MethodSymbol.
      * Should be called only on symbols representing annotation type elements.
      */
     public AnnotationTypeElementDocImpl getAnnotationTypeElementDoc(
             MethodSymbol meth) {
         AnnotationTypeElementDocImpl result =
             (AnnotationTypeElementDocImpl)methodMap.get(meth);
         if (result != null) return result;
         result = new AnnotationTypeElementDocImpl(this, meth);
         methodMap.put(meth, result);
         return result;
     }
 //  private Map<ClassType, ParameterizedTypeImpl> parameterizedTypeMap =
 //          new HashMap<ClassType, ParameterizedTypeImpl>();
     /**
      * Return the ParameterizedType of this instantiation.
 //   * ### Could use Type.sameTypeAs() instead of equality matching in hashmap
 //   * ### to avoid some duplication.
      */
     ParameterizedTypeImpl getParameterizedType(ClassType t) {
         return new ParameterizedTypeImpl(this, t);
 //      ParameterizedTypeImpl result = parameterizedTypeMap.get(t);
 //      if (result != null) return result;
 //      result = new ParameterizedTypeImpl(this, t);
 //      parameterizedTypeMap.put(t, result);
 //      return result;
     }
     TreePath getTreePath(JCCompilationUnit tree) {
         TreePath p = treePaths.get(tree);
         if (p == null)
             treePaths.put(tree, p = new TreePath(tree));
         return p;
     }
     TreePath getTreePath(JCCompilationUnit toplevel, JCClassDecl tree) {
         TreePath p = treePaths.get(tree);
         if (p == null)
             treePaths.put(tree, p = new TreePath(getTreePath(toplevel), tree));
         return p;
     }
     TreePath getTreePath(JCCompilationUnit toplevel, JCClassDecl cdecl, JCTree tree) {
         return new TreePath(getTreePath(toplevel, cdecl), tree);
     }
     /**
      * Set the encoding.
      */
     public void setEncoding(String encoding) {
         this.encoding = encoding;
     }
     /**
      * Get the encoding.
      */
     public String getEncoding() {
         return encoding;
     }
     /**
      * Convert modifier bits from private coding used by
      * the compiler to that of java.lang.reflect.Modifier.
      */
     static int translateModifiers(long flags) {
         int result = 0;
         if ((flags & Flags.ABSTRACT) != 0)
             result |= Modifier.ABSTRACT;
         if ((flags & Flags.FINAL) != 0)
             result |= Modifier.FINAL;
         if ((flags & Flags.INTERFACE) != 0)
             result |= Modifier.INTERFACE;
         if ((flags & Flags.NATIVE) != 0)
             result |= Modifier.NATIVE;
         if ((flags & Flags.PRIVATE) != 0)
             result |= Modifier.PRIVATE;
         if ((flags & Flags.PROTECTED) != 0)
             result |= Modifier.PROTECTED;
         if ((flags & Flags.PUBLIC) != 0)
             result |= Modifier.PUBLIC;
         if ((flags & Flags.STATIC) != 0)
             result |= Modifier.STATIC;
         if ((flags & Flags.SYNCHRONIZED) != 0)
             result |= Modifier.SYNCHRONIZED;
         if ((flags & Flags.TRANSIENT) != 0)
             result |= Modifier.TRANSIENT;
         if ((flags & Flags.VOLATILE) != 0)
             result |= Modifier.VOLATILE;
         return result;
     }
     void initDoclint(Collection<String> opts) {
         ArrayList<String> doclintOpts = new ArrayList<String>();
         for (String opt: opts) {
             doclintOpts.add(opt == null ? DocLint.XMSGS_OPTION : DocLint.XMSGS_CUSTOM_PREFIX + opt);
         }
         if (doclintOpts.isEmpty()) {
             doclintOpts.add(DocLint.XMSGS_OPTION);
         } else if (doclintOpts.size() == 1
                 && doclintOpts.get(0).equals(DocLint.XMSGS_CUSTOM_PREFIX + "none")) {
             return;
         }
         JavacTask t = BasicJavacTask.instance(context);
         doclint = new DocLint();
         doclint.init(t, doclintOpts.toArray(new String[doclintOpts.size()]), false);
     }
     boolean showTagMessages() {
         return (doclint == null);
     }
 }

Mercurial > jdk8-mips64-public > langtools / annotate

src/share/classes/com/sun/tools/javadoc/DocEnv.java@60caf53b98e2 (annotated)

src/share/classes/com/sun/tools/javadoc/DocEnv.java