jdk8-mips64-public/langtools: src/share/classes/com/sun/tools/doclint/DocLint.java@ef537bcc825a

8005137: Rename DocLint.call to DocLint.init which overrides Plugin.init
Reviewed-by: darcy, jjh

     1 /*

     2  * Copyright (c) 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.doclint;

    28 import java.io.File;

    29 import java.io.IOException;

    30 import java.io.PrintWriter;

    31 import java.util.ArrayList;

    32 import java.util.List;

    34 import javax.lang.model.element.Name;

    35 import javax.tools.StandardLocation;

    37 import com.sun.source.doctree.DocCommentTree;

    38 import com.sun.source.tree.ClassTree;

    39 import com.sun.source.tree.CompilationUnitTree;

    40 import com.sun.source.tree.MethodTree;

    41 import com.sun.source.tree.Tree;

    42 import com.sun.source.tree.VariableTree;

    43 import com.sun.source.util.JavacTask;

    44 import com.sun.source.util.Plugin;

    45 import com.sun.source.util.TaskEvent;

    46 import com.sun.source.util.TaskListener;

    47 import com.sun.source.util.TreePath;

    48 import com.sun.source.util.TreePathScanner;

    49 import com.sun.tools.javac.api.JavacTaskImpl;

    50 import com.sun.tools.javac.api.JavacTool;

    51 import com.sun.tools.javac.file.JavacFileManager;

    52 import com.sun.tools.javac.main.JavaCompiler;

    53 import com.sun.tools.javac.util.Context;

    55 /**

    56  * Multi-function entry point for the doc check utility.

    57  *

    58  * This class can be invoked in the following ways:

    59  * <ul>

    60  * <li>From the command line

    61  * <li>From javac, as a plugin

    62  * <li>Directly, via a simple API

    63  * </ul>

    64  *

    65  * <p><b>This is NOT part of any supported API.

    66  * If you write code that depends on this, you do so at your own

    67  * risk.  This code and its internal interfaces are subject to change

    68  * or deletion without notice.</b></p>

    69  */

    70 public class DocLint implements Plugin {

    72     public static final String XMSGS_OPTION = "-Xmsgs";

    73     public static final String XMSGS_CUSTOM_PREFIX = "-Xmsgs:";

    74     private static final String STATS = "-stats";

    76     // <editor-fold defaultstate="collapsed" desc="Command-line entry point">

    77     public static void main(String... args) {

    78         try {

    79             new DocLint().run(args);

    80         } catch (BadArgs e) {

    81             System.err.println(e.getMessage());

    82             System.exit(1);

    83         } catch (IOException e) {

    84             System.err.println(e);

    85             System.exit(2);

    86         }

    87     }

    89     // </editor-fold>

    91     // <editor-fold defaultstate="collapsed" desc="Simple API">

    93     public static class BadArgs extends Exception {

    94         private static final long serialVersionUID = 0;

    95         BadArgs(String code, Object... args) {

    96             this.code = code;

    97             this.args = args;

    98         }

   100         final String code;

   101         final Object[] args;

   102     }

   104     /**

   105      * Simple API entry point.

   106      */

   107     public void run(String... args) throws BadArgs, IOException {

   108         PrintWriter out = new PrintWriter(System.out);

   109         try {

   110             run(out, args);

   111         } finally {

   112             out.flush();

   113         }

   114     }

   116     public void run(PrintWriter out, String... args) throws BadArgs, IOException {

   117         env = new Env();

   118         processArgs(args);

   120         if (needHelp)

   121             showHelp(out);

   123         if (javacFiles.isEmpty()) {

   124             if (!needHelp)

   125                 System.out.println("no files given");

   126         }

   128         JavacTool tool = JavacTool.create();

   130         JavacFileManager fm = new JavacFileManager(new Context(), false, null);

   131         fm.setSymbolFileEnabled(false);

   132         fm.setLocation(StandardLocation.PLATFORM_CLASS_PATH, javacBootClassPath);

   133         fm.setLocation(StandardLocation.CLASS_PATH, javacClassPath);

   134         fm.setLocation(StandardLocation.SOURCE_PATH, javacSourcePath);

   136         JavacTask task = tool.getTask(out, fm, null, javacOpts, null,

   137                 fm.getJavaFileObjectsFromFiles(javacFiles));

   138         Iterable<? extends CompilationUnitTree> units = task.parse();

   139         ((JavacTaskImpl) task).enter();

   141         env.init(task);

   142         checker = new Checker(env);

   144         DeclScanner ds = new DeclScanner() {

   145             @Override

   146             void visitDecl(Tree tree, Name name) {

   147                 TreePath p = getCurrentPath();

   148                 DocCommentTree dc = env.trees.getDocCommentTree(p);

   150                 checker.scan(dc, p);

   151             }

   152         };

   154         ds.scan(units, null);

   156         reportStats(out);

   158         Context ctx = ((JavacTaskImpl) task).getContext();

   159         JavaCompiler c = JavaCompiler.instance(ctx);

   160         c.printCount("error", c.errorCount());

   161         c.printCount("warn", c.warningCount());

   162     }

   164     void processArgs(String... args) throws BadArgs {

   165         javacOpts = new ArrayList<String>();

   166         javacFiles = new ArrayList<File>();

   168         if (args.length == 0)

   169             needHelp = true;

   171         for (int i = 0; i < args.length; i++) {

   172             String arg = args[i];

   173             if (arg.matches("-Xmax(errs|warns)") && i + 1 < args.length) {

   174                 if (args[++i].matches("[0-9]+")) {

   175                     javacOpts.add(arg);

   176                     javacOpts.add(args[i]);

   177                 } else {

   178                     throw new BadArgs("dc.bad.value.for.option", arg, args[i]);

   179                 }

   180             } else if (arg.equals(STATS)) {

   181                 env.messages.setStatsEnabled(true);

   182             } else if (arg.matches("-bootclasspath") && i + 1 < args.length) {

   183                 javacBootClassPath = splitPath(args[++i]);

   184             } else if (arg.matches("-classpath") && i + 1 < args.length) {

   185                 javacClassPath = splitPath(args[++i]);

   186             } else if (arg.matches("-sourcepath") && i + 1 < args.length) {

   187                 javacSourcePath = splitPath(args[++i]);

   188             } else if (arg.equals(XMSGS_OPTION)) {

   189                 env.messages.setOptions(null);

   190             } else if (arg.startsWith(XMSGS_CUSTOM_PREFIX)) {

   191                 env.messages.setOptions(arg.substring(arg.indexOf(":") + 1));

   192             } else if (arg.equals("-h") || arg.equals("-help") || arg.equals("--help")

   193                     || arg.equals("-?") || arg.equals("-usage")) {

   194                 needHelp = true;

   195             } else if (arg.startsWith("-")) {

   196                 throw new BadArgs("dc.bad.option", arg);

   197             } else {

   198                 while (i < args.length)

   199                     javacFiles.add(new File(args[i++]));

   200             }

   201         }

   202     }

   204     void showHelp(PrintWriter out) {

   205         out.println("Usage:");

   206         out.println("    doclint [options] source-files...");

   207         out.println("");

   208         out.println("Options:");

   209         out.println("  -Xmsgs  ");

   210         out.println("    Same as -Xmsgs:all");

   211         out.println("  -Xmsgs:values");

   212         out.println("    Specify categories of issues to be checked, where 'values'");

   213         out.println("    is a comma-separated list of any of the following:");

   214         out.println("      reference      show places where comments contain incorrect");

   215         out.println("                     references to Java source code elements");

   216         out.println("      syntax         show basic syntax errors within comments");

   217         out.println("      html           show issues with HTML tags and attributes");

   218         out.println("      accessibility  show issues for accessibility");

   219         out.println("      missing        show issues with missing documentation");

   220         out.println("      all            all of the above");

   221         out.println("    Precede a value with '-' to negate it");

   222         out.println("    Categories may be qualified by one of:");

   223         out.println("      /public /protected /package /private");

   224         out.println("    For positive categories (not beginning with '-')");

   225         out.println("    the qualifier applies to that access level and above.");

   226         out.println("    For negative categories (beginning with '-')");

   227         out.println("    the qualifier applies to that access level and below.");

   228         out.println("    If a qualifier is missing, the category applies to");

   229         out.println("    all access levels.");

   230         out.println("    For example, -Xmsgs:all,-syntax/private");

   231         out.println("    This will enable all messages, except syntax errors");

   232         out.println("    in the doc comments of private methods.");

   233         out.println("    If no -Xmsgs options are provided, the default is");

   234         out.println("    equivalent to -Xmsgs:all/protected, meaning that");

   235         out.println("    all messages are reported for protected and public");

   236         out.println("    declarations only. ");

   237         out.println("  -h -help --help -usage -?");

   238         out.println("    Show this message.");

   239         out.println("");

   240         out.println("The following javac options are also supported");

   241         out.println("  -bootclasspath, -classpath, -sourcepath, -Xmaxerrs, -Xmaxwarns");

   242         out.println("");

   243         out.println("To run doclint on part of a project, put the compiled classes for your");

   244         out.println("project on the classpath (or bootclasspath), then specify the source files");

   245         out.println("to be checked on the command line.");

   246     }

   248     List<File> splitPath(String path) {

   249         List<File> files = new ArrayList<File>();

   250         for (String f: path.split(File.separator)) {

   251             if (f.length() > 0)

   252                 files.add(new File(f));

   253         }

   254         return files;

   255     }

   257     List<File> javacBootClassPath;

   258     List<File> javacClassPath;

   259     List<File> javacSourcePath;

   260     List<String> javacOpts;

   261     List<File> javacFiles;

   262     boolean needHelp = false;

   264     // </editor-fold>

   266     // <editor-fold defaultstate="collapsed" desc="javac Plugin">

   268     @Override

   269     public String getName() {

   270         return "doclint";

   271     }

   273     @Override

   274     public void init(JavacTask task, String... args) {

   275         init(task, args, true);

   276     }

   278     // </editor-fold>

   280     // <editor-fold defaultstate="collapsed" desc="Embedding API">

   282     public void init(JavacTask task, String[] args, boolean addTaskListener) {

   283         env = new Env();

   284         for (int i = 0; i < args.length; i++) {

   285             String arg = args[i];

   286             if (arg.equals(XMSGS_OPTION)) {

   287                 env.messages.setOptions(null);

   288             } else if (arg.startsWith(XMSGS_CUSTOM_PREFIX)) {

   289                 env.messages.setOptions(arg.substring(arg.indexOf(":") + 1));

   290             } else

   291                 throw new IllegalArgumentException(arg);

   292         }

   293         env.init(task);

   295         checker = new Checker(env);

   297         if (addTaskListener) {

   298             final DeclScanner ds = new DeclScanner() {

   299                 @Override

   300                 void visitDecl(Tree tree, Name name) {

   301                     TreePath p = getCurrentPath();

   302                     DocCommentTree dc = env.trees.getDocCommentTree(p);

   304                     checker.scan(dc, p);

   305                 }

   306             };

   308             TaskListener tl = new TaskListener() {

   309                 @Override

   310                 public void started(TaskEvent e) {

   311                     return;

   312                 }

   314                 @Override

   315                 public void finished(TaskEvent e) {

   316                     switch (e.getKind()) {

   317                         case ENTER:

   318                             ds.scan(e.getCompilationUnit(), null);

   319                     }

   320                 }

   321             };

   323             task.addTaskListener(tl);

   324         }

   325     }

   327     public void scan(TreePath p) {

   328         DocCommentTree dc = env.trees.getDocCommentTree(p);

   329         checker.scan(dc, p);

   330     }

   332     public void reportStats(PrintWriter out) {

   333         env.messages.reportStats(out);

   334     }

   336     // </editor-fold>

   338     Env env;

   339     Checker checker;

   341     public static boolean isValidOption(String opt) {

   342         if (opt.equals(XMSGS_OPTION))

   343            return true;

   344         if (opt.startsWith(XMSGS_CUSTOM_PREFIX))

   345            return Messages.Options.isValidOptions(opt.substring(XMSGS_CUSTOM_PREFIX.length()));

   346         return false;

   347     }

   349     // <editor-fold defaultstate="collapsed" desc="DeclScanner">

   351     static abstract class DeclScanner extends TreePathScanner<Void, Void> {

   352         abstract void visitDecl(Tree tree, Name name);

   354         @Override

   355         public Void visitClass(ClassTree tree, Void ignore) {

   356             visitDecl(tree, tree.getSimpleName());

   357             return super.visitClass(tree, ignore);

   358         }

   360         @Override

   361         public Void visitMethod(MethodTree tree, Void ignore) {

   362             visitDecl(tree, tree.getName());

   363             //return super.visitMethod(tree, ignore);

   364             return null;

   365         }

   367         @Override

   368         public Void visitVariable(VariableTree tree, Void ignore) {

   369             visitDecl(tree, tree.getName());

   370             return super.visitVariable(tree, ignore);

   371         }

   372     }

   374     // </editor-fold>

   376 }

Mercurial > jdk8-mips64-public > langtools / file revision

src/share/classes/com/sun/tools/doclint/DocLint.java@ef537bcc825a

src/share/classes/com/sun/tools/doclint/DocLint.java