Thu, 24 Oct 2013 11:22:50 -0700
8006248: Since addition of -Xdoclint, javadoc ignores unknown tags
Reviewed-by: jjg
jjg@1455 | 1 | /* |
jjg@1506 | 2 | * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved. |
jjg@1455 | 3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
jjg@1455 | 4 | * |
jjg@1455 | 5 | * This code is free software; you can redistribute it and/or modify it |
jjg@1455 | 6 | * under the terms of the GNU General Public License version 2 only, as |
jjg@1455 | 7 | * published by the Free Software Foundation. Oracle designates this |
jjg@1455 | 8 | * particular file as subject to the "Classpath" exception as provided |
jjg@1455 | 9 | * by Oracle in the LICENSE file that accompanied this code. |
jjg@1455 | 10 | * |
jjg@1455 | 11 | * This code is distributed in the hope that it will be useful, but WITHOUT |
jjg@1455 | 12 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
jjg@1455 | 13 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
jjg@1455 | 14 | * version 2 for more details (a copy is included in the LICENSE file that |
jjg@1455 | 15 | * accompanied this code). |
jjg@1455 | 16 | * |
jjg@1455 | 17 | * You should have received a copy of the GNU General Public License version |
jjg@1455 | 18 | * 2 along with this work; if not, write to the Free Software Foundation, |
jjg@1455 | 19 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
jjg@1455 | 20 | * |
jjg@1455 | 21 | * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
jjg@1455 | 22 | * or visit www.oracle.com if you need additional information or have any |
jjg@1455 | 23 | * questions. |
jjg@1455 | 24 | */ |
jjg@1455 | 25 | |
jjg@1455 | 26 | package com.sun.tools.doclint; |
jjg@1455 | 27 | |
jjg@1455 | 28 | import java.io.File; |
jjg@1455 | 29 | import java.io.IOException; |
jjg@1455 | 30 | import java.io.PrintWriter; |
jjg@1455 | 31 | import java.util.ArrayList; |
jjg@2033 | 32 | import java.util.HashSet; |
jjg@2033 | 33 | import java.util.LinkedList; |
jjg@1455 | 34 | import java.util.List; |
jjg@2033 | 35 | import java.util.Queue; |
jjg@2033 | 36 | import java.util.Set; |
jjg@1455 | 37 | |
jjg@1455 | 38 | import javax.lang.model.element.Name; |
jjg@2033 | 39 | import javax.tools.JavaFileObject; |
jjg@1455 | 40 | import javax.tools.StandardLocation; |
jjg@1455 | 41 | |
jjg@1455 | 42 | import com.sun.source.doctree.DocCommentTree; |
jjg@1455 | 43 | import com.sun.source.tree.ClassTree; |
jjg@1455 | 44 | import com.sun.source.tree.CompilationUnitTree; |
jjg@1455 | 45 | import com.sun.source.tree.MethodTree; |
jjg@1455 | 46 | import com.sun.source.tree.Tree; |
jjg@1455 | 47 | import com.sun.source.tree.VariableTree; |
jjg@1455 | 48 | import com.sun.source.util.JavacTask; |
jjg@1455 | 49 | import com.sun.source.util.Plugin; |
jjg@1455 | 50 | import com.sun.source.util.TaskEvent; |
jjg@1455 | 51 | import com.sun.source.util.TaskListener; |
jjg@1455 | 52 | import com.sun.source.util.TreePath; |
jjg@1455 | 53 | import com.sun.source.util.TreePathScanner; |
jjg@1455 | 54 | import com.sun.tools.javac.api.JavacTaskImpl; |
jjg@1455 | 55 | import com.sun.tools.javac.api.JavacTool; |
jjg@1455 | 56 | import com.sun.tools.javac.file.JavacFileManager; |
jjg@1455 | 57 | import com.sun.tools.javac.main.JavaCompiler; |
jjg@1455 | 58 | import com.sun.tools.javac.util.Context; |
jjg@1455 | 59 | |
jjg@1455 | 60 | /** |
jjg@1455 | 61 | * Multi-function entry point for the doc check utility. |
jjg@1455 | 62 | * |
jjg@1455 | 63 | * This class can be invoked in the following ways: |
jjg@1455 | 64 | * <ul> |
jjg@1455 | 65 | * <li>From the command line |
jjg@1455 | 66 | * <li>From javac, as a plugin |
jjg@1455 | 67 | * <li>Directly, via a simple API |
jjg@1455 | 68 | * </ul> |
jjg@1455 | 69 | * |
jjg@1455 | 70 | * <p><b>This is NOT part of any supported API. |
jjg@1455 | 71 | * If you write code that depends on this, you do so at your own |
jjg@1455 | 72 | * risk. This code and its internal interfaces are subject to change |
jjg@1455 | 73 | * or deletion without notice.</b></p> |
jjg@1455 | 74 | */ |
jjg@1455 | 75 | public class DocLint implements Plugin { |
jjg@1455 | 76 | |
jjg@1455 | 77 | public static final String XMSGS_OPTION = "-Xmsgs"; |
jjg@1455 | 78 | public static final String XMSGS_CUSTOM_PREFIX = "-Xmsgs:"; |
jjg@1455 | 79 | private static final String STATS = "-stats"; |
jjg@1668 | 80 | public static final String XIMPLICIT_HEADERS = "-XimplicitHeaders:"; |
bpatel@2169 | 81 | public static final String XCUSTOM_TAGS_PREFIX = "-XcustomTags:"; |
bpatel@2169 | 82 | public static final String TAGS_SEPARATOR = ","; |
jjg@1455 | 83 | |
jjg@1455 | 84 | // <editor-fold defaultstate="collapsed" desc="Command-line entry point"> |
jjg@1455 | 85 | public static void main(String... args) { |
jjg@1796 | 86 | DocLint dl = new DocLint(); |
jjg@1455 | 87 | try { |
jjg@1796 | 88 | dl.run(args); |
jjg@1455 | 89 | } catch (BadArgs e) { |
jjg@1455 | 90 | System.err.println(e.getMessage()); |
jjg@1455 | 91 | System.exit(1); |
jjg@1455 | 92 | } catch (IOException e) { |
jjg@1796 | 93 | System.err.println(dl.localize("dc.main.ioerror", e.getLocalizedMessage())); |
jjg@1455 | 94 | System.exit(2); |
jjg@1455 | 95 | } |
jjg@1455 | 96 | } |
jjg@1455 | 97 | |
jjg@1455 | 98 | // </editor-fold> |
jjg@1455 | 99 | |
jjg@1455 | 100 | // <editor-fold defaultstate="collapsed" desc="Simple API"> |
jjg@1455 | 101 | |
jjg@1796 | 102 | public class BadArgs extends Exception { |
jjg@1455 | 103 | private static final long serialVersionUID = 0; |
jjg@1455 | 104 | BadArgs(String code, Object... args) { |
jjg@1796 | 105 | super(localize(code, args)); |
jjg@1455 | 106 | this.code = code; |
jjg@1455 | 107 | this.args = args; |
jjg@1455 | 108 | } |
jjg@1455 | 109 | |
jjg@1455 | 110 | final String code; |
jjg@1455 | 111 | final Object[] args; |
jjg@1455 | 112 | } |
jjg@1455 | 113 | |
jjg@1455 | 114 | /** |
jjg@1455 | 115 | * Simple API entry point. |
jjg@1455 | 116 | */ |
jjg@1455 | 117 | public void run(String... args) throws BadArgs, IOException { |
jjg@1455 | 118 | PrintWriter out = new PrintWriter(System.out); |
jjg@1455 | 119 | try { |
jjg@1455 | 120 | run(out, args); |
jjg@1455 | 121 | } finally { |
jjg@1455 | 122 | out.flush(); |
jjg@1455 | 123 | } |
jjg@1455 | 124 | } |
jjg@1455 | 125 | |
jjg@1455 | 126 | public void run(PrintWriter out, String... args) throws BadArgs, IOException { |
jjg@1455 | 127 | env = new Env(); |
jjg@1455 | 128 | processArgs(args); |
jjg@1455 | 129 | |
jjg@1455 | 130 | if (needHelp) |
jjg@1455 | 131 | showHelp(out); |
jjg@1455 | 132 | |
jjg@1455 | 133 | if (javacFiles.isEmpty()) { |
jjg@1455 | 134 | if (!needHelp) |
jjg@1796 | 135 | out.println(localize("dc.main.no.files.given")); |
jjg@1455 | 136 | } |
jjg@1455 | 137 | |
jjg@1455 | 138 | JavacTool tool = JavacTool.create(); |
jjg@1455 | 139 | |
jjg@1455 | 140 | JavacFileManager fm = new JavacFileManager(new Context(), false, null); |
jjg@1455 | 141 | fm.setSymbolFileEnabled(false); |
jjg@1455 | 142 | fm.setLocation(StandardLocation.PLATFORM_CLASS_PATH, javacBootClassPath); |
jjg@1455 | 143 | fm.setLocation(StandardLocation.CLASS_PATH, javacClassPath); |
jjg@1455 | 144 | fm.setLocation(StandardLocation.SOURCE_PATH, javacSourcePath); |
jjg@1455 | 145 | |
jjg@1455 | 146 | JavacTask task = tool.getTask(out, fm, null, javacOpts, null, |
jjg@1455 | 147 | fm.getJavaFileObjectsFromFiles(javacFiles)); |
jjg@1455 | 148 | Iterable<? extends CompilationUnitTree> units = task.parse(); |
jjg@1455 | 149 | ((JavacTaskImpl) task).enter(); |
jjg@1455 | 150 | |
jjg@1455 | 151 | env.init(task); |
jjg@1455 | 152 | checker = new Checker(env); |
jjg@1455 | 153 | |
jjg@1455 | 154 | DeclScanner ds = new DeclScanner() { |
jjg@1455 | 155 | @Override |
jjg@1455 | 156 | void visitDecl(Tree tree, Name name) { |
jjg@1455 | 157 | TreePath p = getCurrentPath(); |
jjg@1455 | 158 | DocCommentTree dc = env.trees.getDocCommentTree(p); |
jjg@1455 | 159 | |
jjg@1455 | 160 | checker.scan(dc, p); |
jjg@1455 | 161 | } |
jjg@1455 | 162 | }; |
jjg@1455 | 163 | |
jjg@1455 | 164 | ds.scan(units, null); |
jjg@1455 | 165 | |
jjg@1455 | 166 | reportStats(out); |
jjg@1455 | 167 | |
jjg@1455 | 168 | Context ctx = ((JavacTaskImpl) task).getContext(); |
jjg@1455 | 169 | JavaCompiler c = JavaCompiler.instance(ctx); |
jjg@1455 | 170 | c.printCount("error", c.errorCount()); |
jjg@1455 | 171 | c.printCount("warn", c.warningCount()); |
jjg@1455 | 172 | } |
jjg@1455 | 173 | |
jjg@1455 | 174 | void processArgs(String... args) throws BadArgs { |
jjg@1913 | 175 | javacOpts = new ArrayList<>(); |
jjg@1913 | 176 | javacFiles = new ArrayList<>(); |
jjg@1455 | 177 | |
jjg@1455 | 178 | if (args.length == 0) |
jjg@1455 | 179 | needHelp = true; |
jjg@1455 | 180 | |
jjg@1455 | 181 | for (int i = 0; i < args.length; i++) { |
jjg@1455 | 182 | String arg = args[i]; |
jjg@1455 | 183 | if (arg.matches("-Xmax(errs|warns)") && i + 1 < args.length) { |
jjg@1455 | 184 | if (args[++i].matches("[0-9]+")) { |
jjg@1455 | 185 | javacOpts.add(arg); |
jjg@1455 | 186 | javacOpts.add(args[i]); |
jjg@1455 | 187 | } else { |
jjg@1455 | 188 | throw new BadArgs("dc.bad.value.for.option", arg, args[i]); |
jjg@1455 | 189 | } |
jjg@1455 | 190 | } else if (arg.equals(STATS)) { |
jjg@1455 | 191 | env.messages.setStatsEnabled(true); |
jjg@1506 | 192 | } else if (arg.equals("-bootclasspath") && i + 1 < args.length) { |
jjg@1455 | 193 | javacBootClassPath = splitPath(args[++i]); |
jjg@1506 | 194 | } else if (arg.equals("-classpath") && i + 1 < args.length) { |
jjg@1455 | 195 | javacClassPath = splitPath(args[++i]); |
vromero@1885 | 196 | } else if (arg.equals("-cp") && i + 1 < args.length) { |
vromero@1885 | 197 | javacClassPath = splitPath(args[++i]); |
jjg@1506 | 198 | } else if (arg.equals("-sourcepath") && i + 1 < args.length) { |
jjg@1455 | 199 | javacSourcePath = splitPath(args[++i]); |
jjg@1455 | 200 | } else if (arg.equals(XMSGS_OPTION)) { |
jjg@1455 | 201 | env.messages.setOptions(null); |
jjg@1455 | 202 | } else if (arg.startsWith(XMSGS_CUSTOM_PREFIX)) { |
jjg@1455 | 203 | env.messages.setOptions(arg.substring(arg.indexOf(":") + 1)); |
bpatel@2169 | 204 | } else if (arg.startsWith(XCUSTOM_TAGS_PREFIX)) { |
bpatel@2169 | 205 | env.setCustomTags(arg.substring(arg.indexOf(":") + 1)); |
jjg@1455 | 206 | } else if (arg.equals("-h") || arg.equals("-help") || arg.equals("--help") |
jjg@1455 | 207 | || arg.equals("-?") || arg.equals("-usage")) { |
jjg@1455 | 208 | needHelp = true; |
jjg@1455 | 209 | } else if (arg.startsWith("-")) { |
jjg@1455 | 210 | throw new BadArgs("dc.bad.option", arg); |
jjg@1455 | 211 | } else { |
jjg@1455 | 212 | while (i < args.length) |
jjg@1455 | 213 | javacFiles.add(new File(args[i++])); |
jjg@1455 | 214 | } |
jjg@1455 | 215 | } |
jjg@1455 | 216 | } |
jjg@1455 | 217 | |
jjg@1455 | 218 | void showHelp(PrintWriter out) { |
jjg@1796 | 219 | String msg = localize("dc.main.usage"); |
jjg@1796 | 220 | for (String line: msg.split("\n")) |
jjg@1796 | 221 | out.println(line); |
jjg@1455 | 222 | } |
jjg@1455 | 223 | |
jjg@1455 | 224 | List<File> splitPath(String path) { |
jjg@1913 | 225 | List<File> files = new ArrayList<>(); |
jjg@1506 | 226 | for (String f: path.split(File.pathSeparator)) { |
jjg@1455 | 227 | if (f.length() > 0) |
jjg@1455 | 228 | files.add(new File(f)); |
jjg@1455 | 229 | } |
jjg@1455 | 230 | return files; |
jjg@1455 | 231 | } |
jjg@1455 | 232 | |
jjg@1455 | 233 | List<File> javacBootClassPath; |
jjg@1455 | 234 | List<File> javacClassPath; |
jjg@1455 | 235 | List<File> javacSourcePath; |
jjg@1455 | 236 | List<String> javacOpts; |
jjg@1455 | 237 | List<File> javacFiles; |
jjg@1455 | 238 | boolean needHelp = false; |
jjg@1455 | 239 | |
jjg@1455 | 240 | // </editor-fold> |
jjg@1455 | 241 | |
jjg@1455 | 242 | // <editor-fold defaultstate="collapsed" desc="javac Plugin"> |
jjg@1455 | 243 | |
jjg@1455 | 244 | @Override |
jjg@1455 | 245 | public String getName() { |
jjg@1455 | 246 | return "doclint"; |
jjg@1455 | 247 | } |
jjg@1455 | 248 | |
jjg@1455 | 249 | @Override |
mchung@1458 | 250 | public void init(JavacTask task, String... args) { |
jjg@1455 | 251 | init(task, args, true); |
jjg@1455 | 252 | } |
jjg@1455 | 253 | |
jjg@1455 | 254 | // </editor-fold> |
jjg@1455 | 255 | |
jjg@1455 | 256 | // <editor-fold defaultstate="collapsed" desc="Embedding API"> |
jjg@1455 | 257 | |
jjg@1455 | 258 | public void init(JavacTask task, String[] args, boolean addTaskListener) { |
jjg@1455 | 259 | env = new Env(); |
jjg@1455 | 260 | for (int i = 0; i < args.length; i++) { |
jjg@1455 | 261 | String arg = args[i]; |
jjg@1455 | 262 | if (arg.equals(XMSGS_OPTION)) { |
jjg@1455 | 263 | env.messages.setOptions(null); |
jjg@1455 | 264 | } else if (arg.startsWith(XMSGS_CUSTOM_PREFIX)) { |
jjg@1455 | 265 | env.messages.setOptions(arg.substring(arg.indexOf(":") + 1)); |
jjg@1668 | 266 | } else if (arg.matches(XIMPLICIT_HEADERS + "[1-6]")) { |
jjg@1668 | 267 | char ch = arg.charAt(arg.length() - 1); |
jjg@1668 | 268 | env.setImplicitHeaders(Character.digit(ch, 10)); |
bpatel@2169 | 269 | } else if (arg.startsWith(XCUSTOM_TAGS_PREFIX)) { |
bpatel@2169 | 270 | env.setCustomTags(arg.substring(arg.indexOf(":") + 1)); |
jjg@1455 | 271 | } else |
jjg@1455 | 272 | throw new IllegalArgumentException(arg); |
jjg@1455 | 273 | } |
jjg@1455 | 274 | env.init(task); |
jjg@1455 | 275 | |
jjg@1455 | 276 | checker = new Checker(env); |
jjg@1455 | 277 | |
jjg@1455 | 278 | if (addTaskListener) { |
jjg@1455 | 279 | final DeclScanner ds = new DeclScanner() { |
jjg@1455 | 280 | @Override |
jjg@1455 | 281 | void visitDecl(Tree tree, Name name) { |
jjg@1455 | 282 | TreePath p = getCurrentPath(); |
jjg@1455 | 283 | DocCommentTree dc = env.trees.getDocCommentTree(p); |
jjg@1455 | 284 | |
jjg@1455 | 285 | checker.scan(dc, p); |
jjg@1455 | 286 | } |
jjg@1455 | 287 | }; |
jjg@1455 | 288 | |
jjg@1455 | 289 | TaskListener tl = new TaskListener() { |
jjg@1455 | 290 | @Override |
jjg@1455 | 291 | public void started(TaskEvent e) { |
jjg@2033 | 292 | switch (e.getKind()) { |
jjg@2033 | 293 | case ANALYZE: |
jjg@2033 | 294 | CompilationUnitTree tree; |
jjg@2033 | 295 | while ((tree = todo.poll()) != null) |
jjg@2033 | 296 | ds.scan(tree, null); |
jjg@2033 | 297 | break; |
jjg@2033 | 298 | } |
jjg@1455 | 299 | } |
jjg@1455 | 300 | |
jjg@1455 | 301 | @Override |
jjg@1455 | 302 | public void finished(TaskEvent e) { |
jjg@1455 | 303 | switch (e.getKind()) { |
jjg@2033 | 304 | case PARSE: |
jjg@2033 | 305 | todo.add(e.getCompilationUnit()); |
jjg@2033 | 306 | break; |
jjg@1455 | 307 | } |
jjg@1455 | 308 | } |
jjg@2033 | 309 | |
jjg@2033 | 310 | Queue<CompilationUnitTree> todo = new LinkedList<CompilationUnitTree>(); |
jjg@1455 | 311 | }; |
jjg@1455 | 312 | |
jjg@1455 | 313 | task.addTaskListener(tl); |
jjg@1455 | 314 | } |
jjg@1455 | 315 | } |
jjg@1455 | 316 | |
jjg@1455 | 317 | public void scan(TreePath p) { |
jjg@1455 | 318 | DocCommentTree dc = env.trees.getDocCommentTree(p); |
jjg@1455 | 319 | checker.scan(dc, p); |
jjg@1455 | 320 | } |
jjg@1455 | 321 | |
jjg@1455 | 322 | public void reportStats(PrintWriter out) { |
jjg@1455 | 323 | env.messages.reportStats(out); |
jjg@1455 | 324 | } |
jjg@1455 | 325 | |
jjg@1455 | 326 | // </editor-fold> |
jjg@1455 | 327 | |
jjg@1455 | 328 | Env env; |
jjg@1455 | 329 | Checker checker; |
jjg@1455 | 330 | |
jjg@1455 | 331 | public static boolean isValidOption(String opt) { |
jjg@1455 | 332 | if (opt.equals(XMSGS_OPTION)) |
jjg@1455 | 333 | return true; |
jjg@1455 | 334 | if (opt.startsWith(XMSGS_CUSTOM_PREFIX)) |
jjg@1455 | 335 | return Messages.Options.isValidOptions(opt.substring(XMSGS_CUSTOM_PREFIX.length())); |
jjg@1455 | 336 | return false; |
jjg@1455 | 337 | } |
jjg@1455 | 338 | |
jjg@1796 | 339 | private String localize(String code, Object... args) { |
jjg@1796 | 340 | Messages m = (env != null) ? env.messages : new Messages(null); |
jjg@1796 | 341 | return m.localize(code, args); |
jjg@1796 | 342 | } |
jjg@1796 | 343 | |
jjg@1455 | 344 | // <editor-fold defaultstate="collapsed" desc="DeclScanner"> |
jjg@1455 | 345 | |
jjg@1455 | 346 | static abstract class DeclScanner extends TreePathScanner<Void, Void> { |
jjg@1455 | 347 | abstract void visitDecl(Tree tree, Name name); |
jjg@1455 | 348 | |
jjg@1455 | 349 | @Override |
jjg@1895 | 350 | public Void visitCompilationUnit(CompilationUnitTree tree, Void ignore) { |
jjg@1895 | 351 | if (tree.getPackageName() != null) { |
jjg@1895 | 352 | visitDecl(tree, null); |
jjg@1895 | 353 | } |
jjg@1895 | 354 | return super.visitCompilationUnit(tree, ignore); |
jjg@1895 | 355 | } |
jjg@1895 | 356 | |
jjg@1895 | 357 | @Override |
jjg@1455 | 358 | public Void visitClass(ClassTree tree, Void ignore) { |
jjg@1455 | 359 | visitDecl(tree, tree.getSimpleName()); |
jjg@1455 | 360 | return super.visitClass(tree, ignore); |
jjg@1455 | 361 | } |
jjg@1455 | 362 | |
jjg@1455 | 363 | @Override |
jjg@1455 | 364 | public Void visitMethod(MethodTree tree, Void ignore) { |
jjg@1455 | 365 | visitDecl(tree, tree.getName()); |
jjg@1455 | 366 | //return super.visitMethod(tree, ignore); |
jjg@1455 | 367 | return null; |
jjg@1455 | 368 | } |
jjg@1455 | 369 | |
jjg@1455 | 370 | @Override |
jjg@1455 | 371 | public Void visitVariable(VariableTree tree, Void ignore) { |
jjg@1455 | 372 | visitDecl(tree, tree.getName()); |
jjg@1455 | 373 | return super.visitVariable(tree, ignore); |
jjg@1455 | 374 | } |
jjg@1455 | 375 | } |
jjg@1455 | 376 | |
jjg@1455 | 377 | // </editor-fold> |
jjg@1455 | 378 | |
jjg@1455 | 379 | } |