Thu, 28 Mar 2013 10:49:39 -0700
8006346: doclint should make allowance for headers generated by standard doclet
Reviewed-by: mcimadamore
1 /*
2 * Copyright (c) 2012, 2013, 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;
33 import java.util.regex.Pattern;
35 import javax.lang.model.element.Name;
36 import javax.tools.StandardLocation;
38 import com.sun.source.doctree.DocCommentTree;
39 import com.sun.source.tree.ClassTree;
40 import com.sun.source.tree.CompilationUnitTree;
41 import com.sun.source.tree.MethodTree;
42 import com.sun.source.tree.Tree;
43 import com.sun.source.tree.VariableTree;
44 import com.sun.source.util.JavacTask;
45 import com.sun.source.util.Plugin;
46 import com.sun.source.util.TaskEvent;
47 import com.sun.source.util.TaskListener;
48 import com.sun.source.util.TreePath;
49 import com.sun.source.util.TreePathScanner;
50 import com.sun.tools.javac.api.JavacTaskImpl;
51 import com.sun.tools.javac.api.JavacTool;
52 import com.sun.tools.javac.file.JavacFileManager;
53 import com.sun.tools.javac.main.JavaCompiler;
54 import com.sun.tools.javac.util.Context;
56 /**
57 * Multi-function entry point for the doc check utility.
58 *
59 * This class can be invoked in the following ways:
60 * <ul>
61 * <li>From the command line
62 * <li>From javac, as a plugin
63 * <li>Directly, via a simple API
64 * </ul>
65 *
66 * <p><b>This is NOT part of any supported API.
67 * If you write code that depends on this, you do so at your own
68 * risk. This code and its internal interfaces are subject to change
69 * or deletion without notice.</b></p>
70 */
71 public class DocLint implements Plugin {
73 public static final String XMSGS_OPTION = "-Xmsgs";
74 public static final String XMSGS_CUSTOM_PREFIX = "-Xmsgs:";
75 private static final String STATS = "-stats";
76 public static final String XIMPLICIT_HEADERS = "-XimplicitHeaders:";
78 // <editor-fold defaultstate="collapsed" desc="Command-line entry point">
79 public static void main(String... args) {
80 try {
81 new DocLint().run(args);
82 } catch (BadArgs e) {
83 System.err.println(e.getMessage());
84 System.exit(1);
85 } catch (IOException e) {
86 System.err.println(e);
87 System.exit(2);
88 }
89 }
91 // </editor-fold>
93 // <editor-fold defaultstate="collapsed" desc="Simple API">
95 public static class BadArgs extends Exception {
96 private static final long serialVersionUID = 0;
97 BadArgs(String code, Object... args) {
98 this.code = code;
99 this.args = args;
100 }
102 final String code;
103 final Object[] args;
104 }
106 /**
107 * Simple API entry point.
108 */
109 public void run(String... args) throws BadArgs, IOException {
110 PrintWriter out = new PrintWriter(System.out);
111 try {
112 run(out, args);
113 } finally {
114 out.flush();
115 }
116 }
118 public void run(PrintWriter out, String... args) throws BadArgs, IOException {
119 env = new Env();
120 processArgs(args);
122 if (needHelp)
123 showHelp(out);
125 if (javacFiles.isEmpty()) {
126 if (!needHelp)
127 out.println("no files given");
128 }
130 JavacTool tool = JavacTool.create();
132 JavacFileManager fm = new JavacFileManager(new Context(), false, null);
133 fm.setSymbolFileEnabled(false);
134 fm.setLocation(StandardLocation.PLATFORM_CLASS_PATH, javacBootClassPath);
135 fm.setLocation(StandardLocation.CLASS_PATH, javacClassPath);
136 fm.setLocation(StandardLocation.SOURCE_PATH, javacSourcePath);
138 JavacTask task = tool.getTask(out, fm, null, javacOpts, null,
139 fm.getJavaFileObjectsFromFiles(javacFiles));
140 Iterable<? extends CompilationUnitTree> units = task.parse();
141 ((JavacTaskImpl) task).enter();
143 env.init(task);
144 checker = new Checker(env);
146 DeclScanner ds = new DeclScanner() {
147 @Override
148 void visitDecl(Tree tree, Name name) {
149 TreePath p = getCurrentPath();
150 DocCommentTree dc = env.trees.getDocCommentTree(p);
152 checker.scan(dc, p);
153 }
154 };
156 ds.scan(units, null);
158 reportStats(out);
160 Context ctx = ((JavacTaskImpl) task).getContext();
161 JavaCompiler c = JavaCompiler.instance(ctx);
162 c.printCount("error", c.errorCount());
163 c.printCount("warn", c.warningCount());
164 }
166 void processArgs(String... args) throws BadArgs {
167 javacOpts = new ArrayList<String>();
168 javacFiles = new ArrayList<File>();
170 if (args.length == 0)
171 needHelp = true;
173 for (int i = 0; i < args.length; i++) {
174 String arg = args[i];
175 if (arg.matches("-Xmax(errs|warns)") && i + 1 < args.length) {
176 if (args[++i].matches("[0-9]+")) {
177 javacOpts.add(arg);
178 javacOpts.add(args[i]);
179 } else {
180 throw new BadArgs("dc.bad.value.for.option", arg, args[i]);
181 }
182 } else if (arg.equals(STATS)) {
183 env.messages.setStatsEnabled(true);
184 } else if (arg.equals("-bootclasspath") && i + 1 < args.length) {
185 javacBootClassPath = splitPath(args[++i]);
186 } else if (arg.equals("-classpath") && i + 1 < args.length) {
187 javacClassPath = splitPath(args[++i]);
188 } else if (arg.equals("-sourcepath") && i + 1 < args.length) {
189 javacSourcePath = splitPath(args[++i]);
190 } else if (arg.equals(XMSGS_OPTION)) {
191 env.messages.setOptions(null);
192 } else if (arg.startsWith(XMSGS_CUSTOM_PREFIX)) {
193 env.messages.setOptions(arg.substring(arg.indexOf(":") + 1));
194 } else if (arg.equals("-h") || arg.equals("-help") || arg.equals("--help")
195 || arg.equals("-?") || arg.equals("-usage")) {
196 needHelp = true;
197 } else if (arg.startsWith("-")) {
198 throw new BadArgs("dc.bad.option", arg);
199 } else {
200 while (i < args.length)
201 javacFiles.add(new File(args[i++]));
202 }
203 }
204 }
206 void showHelp(PrintWriter out) {
207 out.println("Usage:");
208 out.println(" doclint [options] source-files...");
209 out.println("");
210 out.println("Options:");
211 out.println(" -Xmsgs ");
212 out.println(" Same as -Xmsgs:all");
213 out.println(" -Xmsgs:values");
214 out.println(" Specify categories of issues to be checked, where 'values'");
215 out.println(" is a comma-separated list of any of the following:");
216 out.println(" reference show places where comments contain incorrect");
217 out.println(" references to Java source code elements");
218 out.println(" syntax show basic syntax errors within comments");
219 out.println(" html show issues with HTML tags and attributes");
220 out.println(" accessibility show issues for accessibility");
221 out.println(" missing show issues with missing documentation");
222 out.println(" all all of the above");
223 out.println(" Precede a value with '-' to negate it");
224 out.println(" Categories may be qualified by one of:");
225 out.println(" /public /protected /package /private");
226 out.println(" For positive categories (not beginning with '-')");
227 out.println(" the qualifier applies to that access level and above.");
228 out.println(" For negative categories (beginning with '-')");
229 out.println(" the qualifier applies to that access level and below.");
230 out.println(" If a qualifier is missing, the category applies to");
231 out.println(" all access levels.");
232 out.println(" For example, -Xmsgs:all,-syntax/private");
233 out.println(" This will enable all messages, except syntax errors");
234 out.println(" in the doc comments of private methods.");
235 out.println(" If no -Xmsgs options are provided, the default is");
236 out.println(" equivalent to -Xmsgs:all/protected, meaning that");
237 out.println(" all messages are reported for protected and public");
238 out.println(" declarations only. ");
239 out.println(" -stats");
240 out.println(" Report statistics on the reported issues.");
241 out.println(" -h -help --help -usage -?");
242 out.println(" Show this message.");
243 out.println("");
244 out.println("The following javac options are also supported");
245 out.println(" -bootclasspath, -classpath, -sourcepath, -Xmaxerrs, -Xmaxwarns");
246 out.println("");
247 out.println("To run doclint on part of a project, put the compiled classes for your");
248 out.println("project on the classpath (or bootclasspath), then specify the source files");
249 out.println("to be checked on the command line.");
250 }
252 List<File> splitPath(String path) {
253 List<File> files = new ArrayList<File>();
254 for (String f: path.split(File.pathSeparator)) {
255 if (f.length() > 0)
256 files.add(new File(f));
257 }
258 return files;
259 }
261 List<File> javacBootClassPath;
262 List<File> javacClassPath;
263 List<File> javacSourcePath;
264 List<String> javacOpts;
265 List<File> javacFiles;
266 boolean needHelp = false;
268 // </editor-fold>
270 // <editor-fold defaultstate="collapsed" desc="javac Plugin">
272 @Override
273 public String getName() {
274 return "doclint";
275 }
277 @Override
278 public void init(JavacTask task, String... args) {
279 init(task, args, true);
280 }
282 // </editor-fold>
284 // <editor-fold defaultstate="collapsed" desc="Embedding API">
286 public void init(JavacTask task, String[] args, boolean addTaskListener) {
287 env = new Env();
288 for (int i = 0; i < args.length; i++) {
289 String arg = args[i];
290 if (arg.equals(XMSGS_OPTION)) {
291 env.messages.setOptions(null);
292 } else if (arg.startsWith(XMSGS_CUSTOM_PREFIX)) {
293 env.messages.setOptions(arg.substring(arg.indexOf(":") + 1));
294 } else if (arg.matches(XIMPLICIT_HEADERS + "[1-6]")) {
295 char ch = arg.charAt(arg.length() - 1);
296 env.setImplicitHeaders(Character.digit(ch, 10));
297 } else
298 throw new IllegalArgumentException(arg);
299 }
300 env.init(task);
302 checker = new Checker(env);
304 if (addTaskListener) {
305 final DeclScanner ds = new DeclScanner() {
306 @Override
307 void visitDecl(Tree tree, Name name) {
308 TreePath p = getCurrentPath();
309 DocCommentTree dc = env.trees.getDocCommentTree(p);
311 checker.scan(dc, p);
312 }
313 };
315 TaskListener tl = new TaskListener() {
316 @Override
317 public void started(TaskEvent e) {
318 return;
319 }
321 @Override
322 public void finished(TaskEvent e) {
323 switch (e.getKind()) {
324 case ENTER:
325 ds.scan(e.getCompilationUnit(), null);
326 }
327 }
328 };
330 task.addTaskListener(tl);
331 }
332 }
334 public void scan(TreePath p) {
335 DocCommentTree dc = env.trees.getDocCommentTree(p);
336 checker.scan(dc, p);
337 }
339 public void reportStats(PrintWriter out) {
340 env.messages.reportStats(out);
341 }
343 // </editor-fold>
345 Env env;
346 Checker checker;
348 public static boolean isValidOption(String opt) {
349 if (opt.equals(XMSGS_OPTION))
350 return true;
351 if (opt.startsWith(XMSGS_CUSTOM_PREFIX))
352 return Messages.Options.isValidOptions(opt.substring(XMSGS_CUSTOM_PREFIX.length()));
353 return false;
354 }
356 // <editor-fold defaultstate="collapsed" desc="DeclScanner">
358 static abstract class DeclScanner extends TreePathScanner<Void, Void> {
359 abstract void visitDecl(Tree tree, Name name);
361 @Override
362 public Void visitClass(ClassTree tree, Void ignore) {
363 visitDecl(tree, tree.getSimpleName());
364 return super.visitClass(tree, ignore);
365 }
367 @Override
368 public Void visitMethod(MethodTree tree, Void ignore) {
369 visitDecl(tree, tree.getName());
370 //return super.visitMethod(tree, ignore);
371 return null;
372 }
374 @Override
375 public Void visitVariable(VariableTree tree, Void ignore) {
376 visitDecl(tree, tree.getName());
377 return super.visitVariable(tree, ignore);
378 }
379 }
381 // </editor-fold>
383 }