1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/classes/com/sun/tools/doclint/Checker.java Wed Apr 27 01:34:52 2016 +0800
1.3 @@ -0,0 +1,971 @@
1.4 +/*
1.5 + * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package com.sun.tools.doclint;
1.30 +
1.31 +import java.io.IOException;
1.32 +import java.io.StringWriter;
1.33 +import java.net.URI;
1.34 +import java.net.URISyntaxException;
1.35 +import java.util.Deque;
1.36 +import java.util.EnumSet;
1.37 +import java.util.HashMap;
1.38 +import java.util.HashSet;
1.39 +import java.util.LinkedList;
1.40 +import java.util.List;
1.41 +import java.util.Map;
1.42 +import java.util.Set;
1.43 +import java.util.regex.Matcher;
1.44 +import java.util.regex.Pattern;
1.45 +
1.46 +import javax.lang.model.element.Element;
1.47 +import javax.lang.model.element.ElementKind;
1.48 +import javax.lang.model.element.ExecutableElement;
1.49 +import javax.lang.model.element.Name;
1.50 +import javax.lang.model.element.VariableElement;
1.51 +import javax.lang.model.type.TypeKind;
1.52 +import javax.lang.model.type.TypeMirror;
1.53 +import javax.tools.Diagnostic.Kind;
1.54 +import javax.tools.JavaFileObject;
1.55 +
1.56 +import com.sun.source.doctree.AttributeTree;
1.57 +import com.sun.source.doctree.AuthorTree;
1.58 +import com.sun.source.doctree.DocCommentTree;
1.59 +import com.sun.source.doctree.DocRootTree;
1.60 +import com.sun.source.doctree.DocTree;
1.61 +import com.sun.source.doctree.EndElementTree;
1.62 +import com.sun.source.doctree.EntityTree;
1.63 +import com.sun.source.doctree.ErroneousTree;
1.64 +import com.sun.source.doctree.IdentifierTree;
1.65 +import com.sun.source.doctree.InheritDocTree;
1.66 +import com.sun.source.doctree.LinkTree;
1.67 +import com.sun.source.doctree.LiteralTree;
1.68 +import com.sun.source.doctree.ParamTree;
1.69 +import com.sun.source.doctree.ReferenceTree;
1.70 +import com.sun.source.doctree.ReturnTree;
1.71 +import com.sun.source.doctree.SerialDataTree;
1.72 +import com.sun.source.doctree.SerialFieldTree;
1.73 +import com.sun.source.doctree.SinceTree;
1.74 +import com.sun.source.doctree.StartElementTree;
1.75 +import com.sun.source.doctree.TextTree;
1.76 +import com.sun.source.doctree.ThrowsTree;
1.77 +import com.sun.source.doctree.UnknownBlockTagTree;
1.78 +import com.sun.source.doctree.UnknownInlineTagTree;
1.79 +import com.sun.source.doctree.ValueTree;
1.80 +import com.sun.source.doctree.VersionTree;
1.81 +import com.sun.source.util.DocTreePath;
1.82 +import com.sun.source.util.DocTreePathScanner;
1.83 +import com.sun.source.util.TreePath;
1.84 +import com.sun.tools.doclint.HtmlTag.AttrKind;
1.85 +import com.sun.tools.javac.tree.DocPretty;
1.86 +import com.sun.tools.javac.util.StringUtils;
1.87 +import static com.sun.tools.doclint.Messages.Group.*;
1.88 +
1.89 +
1.90 +/**
1.91 + * Validate a doc comment.
1.92 + *
1.93 + * <p><b>This is NOT part of any supported API.
1.94 + * If you write code that depends on this, you do so at your own
1.95 + * risk. This code and its internal interfaces are subject to change
1.96 + * or deletion without notice.</b></p>
1.97 + */
1.98 +public class Checker extends DocTreePathScanner<Void, Void> {
1.99 + final Env env;
1.100 +
1.101 + Set<Element> foundParams = new HashSet<>();
1.102 + Set<TypeMirror> foundThrows = new HashSet<>();
1.103 + Map<Element, Set<String>> foundAnchors = new HashMap<>();
1.104 + boolean foundInheritDoc = false;
1.105 + boolean foundReturn = false;
1.106 +
1.107 + public enum Flag {
1.108 + TABLE_HAS_CAPTION,
1.109 + HAS_ELEMENT,
1.110 + HAS_INLINE_TAG,
1.111 + HAS_TEXT,
1.112 + REPORTED_BAD_INLINE
1.113 + }
1.114 +
1.115 + static class TagStackItem {
1.116 + final DocTree tree; // typically, but not always, StartElementTree
1.117 + final HtmlTag tag;
1.118 + final Set<HtmlTag.Attr> attrs;
1.119 + final Set<Flag> flags;
1.120 + TagStackItem(DocTree tree, HtmlTag tag) {
1.121 + this.tree = tree;
1.122 + this.tag = tag;
1.123 + attrs = EnumSet.noneOf(HtmlTag.Attr.class);
1.124 + flags = EnumSet.noneOf(Flag.class);
1.125 + }
1.126 + @Override
1.127 + public String toString() {
1.128 + return String.valueOf(tag);
1.129 + }
1.130 + }
1.131 +
1.132 + private Deque<TagStackItem> tagStack; // TODO: maybe want to record starting tree as well
1.133 + private HtmlTag currHeaderTag;
1.134 +
1.135 + private final int implicitHeaderLevel;
1.136 +
1.137 + // <editor-fold defaultstate="collapsed" desc="Top level">
1.138 +
1.139 + Checker(Env env) {
1.140 + env.getClass();
1.141 + this.env = env;
1.142 + tagStack = new LinkedList<>();
1.143 + implicitHeaderLevel = env.implicitHeaderLevel;
1.144 + }
1.145 +
1.146 + public Void scan(DocCommentTree tree, TreePath p) {
1.147 + env.setCurrent(p, tree);
1.148 +
1.149 + boolean isOverridingMethod = !env.currOverriddenMethods.isEmpty();
1.150 +
1.151 + if (p.getLeaf() == p.getCompilationUnit()) {
1.152 + // If p points to a compilation unit, the implied declaration is the
1.153 + // package declaration (if any) for the compilation unit.
1.154 + // Handle this case specially, because doc comments are only
1.155 + // expected in package-info files.
1.156 + JavaFileObject fo = p.getCompilationUnit().getSourceFile();
1.157 + boolean isPkgInfo = fo.isNameCompatible("package-info", JavaFileObject.Kind.SOURCE);
1.158 + if (tree == null) {
1.159 + if (isPkgInfo)
1.160 + reportMissing("dc.missing.comment");
1.161 + return null;
1.162 + } else {
1.163 + if (!isPkgInfo)
1.164 + reportReference("dc.unexpected.comment");
1.165 + }
1.166 + } else {
1.167 + if (tree == null) {
1.168 + if (!isSynthetic() && !isOverridingMethod)
1.169 + reportMissing("dc.missing.comment");
1.170 + return null;
1.171 + }
1.172 + }
1.173 +
1.174 + tagStack.clear();
1.175 + currHeaderTag = null;
1.176 +
1.177 + foundParams.clear();
1.178 + foundThrows.clear();
1.179 + foundInheritDoc = false;
1.180 + foundReturn = false;
1.181 +
1.182 + scan(new DocTreePath(p, tree), null);
1.183 +
1.184 + if (!isOverridingMethod) {
1.185 + switch (env.currElement.getKind()) {
1.186 + case METHOD:
1.187 + case CONSTRUCTOR: {
1.188 + ExecutableElement ee = (ExecutableElement) env.currElement;
1.189 + checkParamsDocumented(ee.getTypeParameters());
1.190 + checkParamsDocumented(ee.getParameters());
1.191 + switch (ee.getReturnType().getKind()) {
1.192 + case VOID:
1.193 + case NONE:
1.194 + break;
1.195 + default:
1.196 + if (!foundReturn
1.197 + && !foundInheritDoc
1.198 + && !env.types.isSameType(ee.getReturnType(), env.java_lang_Void)) {
1.199 + reportMissing("dc.missing.return");
1.200 + }
1.201 + }
1.202 + checkThrowsDocumented(ee.getThrownTypes());
1.203 + }
1.204 + }
1.205 + }
1.206 +
1.207 + return null;
1.208 + }
1.209 +
1.210 + private void reportMissing(String code, Object... args) {
1.211 + env.messages.report(MISSING, Kind.WARNING, env.currPath.getLeaf(), code, args);
1.212 + }
1.213 +
1.214 + private void reportReference(String code, Object... args) {
1.215 + env.messages.report(REFERENCE, Kind.WARNING, env.currPath.getLeaf(), code, args);
1.216 + }
1.217 +
1.218 + @Override
1.219 + public Void visitDocComment(DocCommentTree tree, Void ignore) {
1.220 + super.visitDocComment(tree, ignore);
1.221 + for (TagStackItem tsi: tagStack) {
1.222 + warnIfEmpty(tsi, null);
1.223 + if (tsi.tree.getKind() == DocTree.Kind.START_ELEMENT
1.224 + && tsi.tag.endKind == HtmlTag.EndKind.REQUIRED) {
1.225 + StartElementTree t = (StartElementTree) tsi.tree;
1.226 + env.messages.error(HTML, t, "dc.tag.not.closed", t.getName());
1.227 + }
1.228 + }
1.229 + return null;
1.230 + }
1.231 + // </editor-fold>
1.232 +
1.233 + // <editor-fold defaultstate="collapsed" desc="Text and entities.">
1.234 +
1.235 + @Override
1.236 + public Void visitText(TextTree tree, Void ignore) {
1.237 + if (hasNonWhitespace(tree)) {
1.238 + checkAllowsText(tree);
1.239 + markEnclosingTag(Flag.HAS_TEXT);
1.240 + }
1.241 + return null;
1.242 + }
1.243 +
1.244 + @Override
1.245 + public Void visitEntity(EntityTree tree, Void ignore) {
1.246 + checkAllowsText(tree);
1.247 + markEnclosingTag(Flag.HAS_TEXT);
1.248 + String name = tree.getName().toString();
1.249 + if (name.startsWith("#")) {
1.250 + int v = StringUtils.toLowerCase(name).startsWith("#x")
1.251 + ? Integer.parseInt(name.substring(2), 16)
1.252 + : Integer.parseInt(name.substring(1), 10);
1.253 + if (!Entity.isValid(v)) {
1.254 + env.messages.error(HTML, tree, "dc.entity.invalid", name);
1.255 + }
1.256 + } else if (!Entity.isValid(name)) {
1.257 + env.messages.error(HTML, tree, "dc.entity.invalid", name);
1.258 + }
1.259 + return null;
1.260 + }
1.261 +
1.262 + void checkAllowsText(DocTree tree) {
1.263 + TagStackItem top = tagStack.peek();
1.264 + if (top != null
1.265 + && top.tree.getKind() == DocTree.Kind.START_ELEMENT
1.266 + && !top.tag.acceptsText()) {
1.267 + if (top.flags.add(Flag.REPORTED_BAD_INLINE)) {
1.268 + env.messages.error(HTML, tree, "dc.text.not.allowed",
1.269 + ((StartElementTree) top.tree).getName());
1.270 + }
1.271 + }
1.272 + }
1.273 +
1.274 + // </editor-fold>
1.275 +
1.276 + // <editor-fold defaultstate="collapsed" desc="HTML elements">
1.277 +
1.278 + @Override
1.279 + public Void visitStartElement(StartElementTree tree, Void ignore) {
1.280 + final Name treeName = tree.getName();
1.281 + final HtmlTag t = HtmlTag.get(treeName);
1.282 + if (t == null) {
1.283 + env.messages.error(HTML, tree, "dc.tag.unknown", treeName);
1.284 + } else {
1.285 + boolean done = false;
1.286 + for (TagStackItem tsi: tagStack) {
1.287 + if (tsi.tag.accepts(t)) {
1.288 + while (tagStack.peek() != tsi) {
1.289 + warnIfEmpty(tagStack.peek(), null);
1.290 + tagStack.pop();
1.291 + }
1.292 + done = true;
1.293 + break;
1.294 + } else if (tsi.tag.endKind != HtmlTag.EndKind.OPTIONAL) {
1.295 + done = true;
1.296 + break;
1.297 + }
1.298 + }
1.299 + if (!done && HtmlTag.BODY.accepts(t)) {
1.300 + while (!tagStack.isEmpty()) {
1.301 + warnIfEmpty(tagStack.peek(), null);
1.302 + tagStack.pop();
1.303 + }
1.304 + }
1.305 +
1.306 + markEnclosingTag(Flag.HAS_ELEMENT);
1.307 + checkStructure(tree, t);
1.308 +
1.309 + // tag specific checks
1.310 + switch (t) {
1.311 + // check for out of sequence headers, such as <h1>...</h1> <h3>...</h3>
1.312 + case H1: case H2: case H3: case H4: case H5: case H6:
1.313 + checkHeader(tree, t);
1.314 + break;
1.315 + }
1.316 +
1.317 + if (t.flags.contains(HtmlTag.Flag.NO_NEST)) {
1.318 + for (TagStackItem i: tagStack) {
1.319 + if (t == i.tag) {
1.320 + env.messages.warning(HTML, tree, "dc.tag.nested.not.allowed", treeName);
1.321 + break;
1.322 + }
1.323 + }
1.324 + }
1.325 + }
1.326 +
1.327 + // check for self closing tags, such as <a id="name"/>
1.328 + if (tree.isSelfClosing()) {
1.329 + env.messages.error(HTML, tree, "dc.tag.self.closing", treeName);
1.330 + }
1.331 +
1.332 + try {
1.333 + TagStackItem parent = tagStack.peek();
1.334 + TagStackItem top = new TagStackItem(tree, t);
1.335 + tagStack.push(top);
1.336 +
1.337 + super.visitStartElement(tree, ignore);
1.338 +
1.339 + // handle attributes that may or may not have been found in start element
1.340 + if (t != null) {
1.341 + switch (t) {
1.342 + case CAPTION:
1.343 + if (parent != null && parent.tag == HtmlTag.TABLE)
1.344 + parent.flags.add(Flag.TABLE_HAS_CAPTION);
1.345 + break;
1.346 +
1.347 + case IMG:
1.348 + if (!top.attrs.contains(HtmlTag.Attr.ALT))
1.349 + env.messages.error(ACCESSIBILITY, tree, "dc.no.alt.attr.for.image");
1.350 + break;
1.351 + }
1.352 + }
1.353 +
1.354 + return null;
1.355 + } finally {
1.356 +
1.357 + if (t == null || t.endKind == HtmlTag.EndKind.NONE)
1.358 + tagStack.pop();
1.359 + }
1.360 + }
1.361 +
1.362 + private void checkStructure(StartElementTree tree, HtmlTag t) {
1.363 + Name treeName = tree.getName();
1.364 + TagStackItem top = tagStack.peek();
1.365 + switch (t.blockType) {
1.366 + case BLOCK:
1.367 + if (top == null || top.tag.accepts(t))
1.368 + return;
1.369 +
1.370 + switch (top.tree.getKind()) {
1.371 + case START_ELEMENT: {
1.372 + if (top.tag.blockType == HtmlTag.BlockType.INLINE) {
1.373 + Name name = ((StartElementTree) top.tree).getName();
1.374 + env.messages.error(HTML, tree, "dc.tag.not.allowed.inline.element",
1.375 + treeName, name);
1.376 + return;
1.377 + }
1.378 + }
1.379 + break;
1.380 +
1.381 + case LINK:
1.382 + case LINK_PLAIN: {
1.383 + String name = top.tree.getKind().tagName;
1.384 + env.messages.error(HTML, tree, "dc.tag.not.allowed.inline.tag",
1.385 + treeName, name);
1.386 + return;
1.387 + }
1.388 + }
1.389 + break;
1.390 +
1.391 + case INLINE:
1.392 + if (top == null || top.tag.accepts(t))
1.393 + return;
1.394 + break;
1.395 +
1.396 + case LIST_ITEM:
1.397 + case TABLE_ITEM:
1.398 + if (top != null) {
1.399 + // reset this flag so subsequent bad inline content gets reported
1.400 + top.flags.remove(Flag.REPORTED_BAD_INLINE);
1.401 + if (top.tag.accepts(t))
1.402 + return;
1.403 + }
1.404 + break;
1.405 +
1.406 + case OTHER:
1.407 + env.messages.error(HTML, tree, "dc.tag.not.allowed", treeName);
1.408 + return;
1.409 + }
1.410 +
1.411 + env.messages.error(HTML, tree, "dc.tag.not.allowed.here", treeName);
1.412 + }
1.413 +
1.414 + private void checkHeader(StartElementTree tree, HtmlTag tag) {
1.415 + // verify the new tag
1.416 + if (getHeaderLevel(tag) > getHeaderLevel(currHeaderTag) + 1) {
1.417 + if (currHeaderTag == null) {
1.418 + env.messages.error(ACCESSIBILITY, tree, "dc.tag.header.sequence.1", tag);
1.419 + } else {
1.420 + env.messages.error(ACCESSIBILITY, tree, "dc.tag.header.sequence.2",
1.421 + tag, currHeaderTag);
1.422 + }
1.423 + }
1.424 +
1.425 + currHeaderTag = tag;
1.426 + }
1.427 +
1.428 + private int getHeaderLevel(HtmlTag tag) {
1.429 + if (tag == null)
1.430 + return implicitHeaderLevel;
1.431 + switch (tag) {
1.432 + case H1: return 1;
1.433 + case H2: return 2;
1.434 + case H3: return 3;
1.435 + case H4: return 4;
1.436 + case H5: return 5;
1.437 + case H6: return 6;
1.438 + default: throw new IllegalArgumentException();
1.439 + }
1.440 + }
1.441 +
1.442 + @Override
1.443 + public Void visitEndElement(EndElementTree tree, Void ignore) {
1.444 + final Name treeName = tree.getName();
1.445 + final HtmlTag t = HtmlTag.get(treeName);
1.446 + if (t == null) {
1.447 + env.messages.error(HTML, tree, "dc.tag.unknown", treeName);
1.448 + } else if (t.endKind == HtmlTag.EndKind.NONE) {
1.449 + env.messages.error(HTML, tree, "dc.tag.end.not.permitted", treeName);
1.450 + } else {
1.451 + boolean done = false;
1.452 + while (!tagStack.isEmpty()) {
1.453 + TagStackItem top = tagStack.peek();
1.454 + if (t == top.tag) {
1.455 + switch (t) {
1.456 + case TABLE:
1.457 + if (!top.attrs.contains(HtmlTag.Attr.SUMMARY)
1.458 + && !top.flags.contains(Flag.TABLE_HAS_CAPTION)) {
1.459 + env.messages.error(ACCESSIBILITY, tree,
1.460 + "dc.no.summary.or.caption.for.table");
1.461 + }
1.462 + }
1.463 + warnIfEmpty(top, tree);
1.464 + tagStack.pop();
1.465 + done = true;
1.466 + break;
1.467 + } else if (top.tag == null || top.tag.endKind != HtmlTag.EndKind.REQUIRED) {
1.468 + tagStack.pop();
1.469 + } else {
1.470 + boolean found = false;
1.471 + for (TagStackItem si: tagStack) {
1.472 + if (si.tag == t) {
1.473 + found = true;
1.474 + break;
1.475 + }
1.476 + }
1.477 + if (found && top.tree.getKind() == DocTree.Kind.START_ELEMENT) {
1.478 + env.messages.error(HTML, top.tree, "dc.tag.start.unmatched",
1.479 + ((StartElementTree) top.tree).getName());
1.480 + tagStack.pop();
1.481 + } else {
1.482 + env.messages.error(HTML, tree, "dc.tag.end.unexpected", treeName);
1.483 + done = true;
1.484 + break;
1.485 + }
1.486 + }
1.487 + }
1.488 +
1.489 + if (!done && tagStack.isEmpty()) {
1.490 + env.messages.error(HTML, tree, "dc.tag.end.unexpected", treeName);
1.491 + }
1.492 + }
1.493 +
1.494 + return super.visitEndElement(tree, ignore);
1.495 + }
1.496 +
1.497 + void warnIfEmpty(TagStackItem tsi, DocTree endTree) {
1.498 + if (tsi.tag != null && tsi.tree instanceof StartElementTree) {
1.499 + if (tsi.tag.flags.contains(HtmlTag.Flag.EXPECT_CONTENT)
1.500 + && !tsi.flags.contains(Flag.HAS_TEXT)
1.501 + && !tsi.flags.contains(Flag.HAS_ELEMENT)
1.502 + && !tsi.flags.contains(Flag.HAS_INLINE_TAG)) {
1.503 + DocTree tree = (endTree != null) ? endTree : tsi.tree;
1.504 + Name treeName = ((StartElementTree) tsi.tree).getName();
1.505 + env.messages.warning(HTML, tree, "dc.tag.empty", treeName);
1.506 + }
1.507 + }
1.508 + }
1.509 +
1.510 + // </editor-fold>
1.511 +
1.512 + // <editor-fold defaultstate="collapsed" desc="HTML attributes">
1.513 +
1.514 + @Override @SuppressWarnings("fallthrough")
1.515 + public Void visitAttribute(AttributeTree tree, Void ignore) {
1.516 + HtmlTag currTag = tagStack.peek().tag;
1.517 + if (currTag != null) {
1.518 + Name name = tree.getName();
1.519 + HtmlTag.Attr attr = currTag.getAttr(name);
1.520 + if (attr != null) {
1.521 + boolean first = tagStack.peek().attrs.add(attr);
1.522 + if (!first)
1.523 + env.messages.error(HTML, tree, "dc.attr.repeated", name);
1.524 + }
1.525 + AttrKind k = currTag.getAttrKind(name);
1.526 + switch (k) {
1.527 + case OK:
1.528 + break;
1.529 +
1.530 + case INVALID:
1.531 + env.messages.error(HTML, tree, "dc.attr.unknown", name);
1.532 + break;
1.533 +
1.534 + case OBSOLETE:
1.535 + env.messages.warning(ACCESSIBILITY, tree, "dc.attr.obsolete", name);
1.536 + break;
1.537 +
1.538 + case USE_CSS:
1.539 + env.messages.warning(ACCESSIBILITY, tree, "dc.attr.obsolete.use.css", name);
1.540 + break;
1.541 + }
1.542 +
1.543 + if (attr != null) {
1.544 + switch (attr) {
1.545 + case NAME:
1.546 + if (currTag != HtmlTag.A) {
1.547 + break;
1.548 + }
1.549 + // fallthrough
1.550 + case ID:
1.551 + String value = getAttrValue(tree);
1.552 + if (value == null) {
1.553 + env.messages.error(HTML, tree, "dc.anchor.value.missing");
1.554 + } else {
1.555 + if (!validName.matcher(value).matches()) {
1.556 + env.messages.error(HTML, tree, "dc.invalid.anchor", value);
1.557 + }
1.558 + if (!checkAnchor(value)) {
1.559 + env.messages.error(HTML, tree, "dc.anchor.already.defined", value);
1.560 + }
1.561 + }
1.562 + break;
1.563 +
1.564 + case HREF:
1.565 + if (currTag == HtmlTag.A) {
1.566 + String v = getAttrValue(tree);
1.567 + if (v == null || v.isEmpty()) {
1.568 + env.messages.error(HTML, tree, "dc.attr.lacks.value");
1.569 + } else {
1.570 + Matcher m = docRoot.matcher(v);
1.571 + if (m.matches()) {
1.572 + String rest = m.group(2);
1.573 + if (!rest.isEmpty())
1.574 + checkURI(tree, rest);
1.575 + } else {
1.576 + checkURI(tree, v);
1.577 + }
1.578 + }
1.579 + }
1.580 + break;
1.581 +
1.582 + case VALUE:
1.583 + if (currTag == HtmlTag.LI) {
1.584 + String v = getAttrValue(tree);
1.585 + if (v == null || v.isEmpty()) {
1.586 + env.messages.error(HTML, tree, "dc.attr.lacks.value");
1.587 + } else if (!validNumber.matcher(v).matches()) {
1.588 + env.messages.error(HTML, tree, "dc.attr.not.number");
1.589 + }
1.590 + }
1.591 + break;
1.592 + }
1.593 + }
1.594 + }
1.595 +
1.596 + // TODO: basic check on value
1.597 +
1.598 + return super.visitAttribute(tree, ignore);
1.599 + }
1.600 +
1.601 + private boolean checkAnchor(String name) {
1.602 + Element e = getEnclosingPackageOrClass(env.currElement);
1.603 + if (e == null)
1.604 + return true;
1.605 + Set<String> set = foundAnchors.get(e);
1.606 + if (set == null)
1.607 + foundAnchors.put(e, set = new HashSet<>());
1.608 + return set.add(name);
1.609 + }
1.610 +
1.611 + private Element getEnclosingPackageOrClass(Element e) {
1.612 + while (e != null) {
1.613 + switch (e.getKind()) {
1.614 + case CLASS:
1.615 + case ENUM:
1.616 + case INTERFACE:
1.617 + case PACKAGE:
1.618 + return e;
1.619 + default:
1.620 + e = e.getEnclosingElement();
1.621 + }
1.622 + }
1.623 + return e;
1.624 + }
1.625 +
1.626 + // http://www.w3.org/TR/html401/types.html#type-name
1.627 + private static final Pattern validName = Pattern.compile("[A-Za-z][A-Za-z0-9-_:.]*");
1.628 +
1.629 + private static final Pattern validNumber = Pattern.compile("-?[0-9]+");
1.630 +
1.631 + // pattern to remove leading {@docRoot}/?
1.632 + private static final Pattern docRoot = Pattern.compile("(?i)(\\{@docRoot *\\}/?)?(.*)");
1.633 +
1.634 + private String getAttrValue(AttributeTree tree) {
1.635 + if (tree.getValue() == null)
1.636 + return null;
1.637 +
1.638 + StringWriter sw = new StringWriter();
1.639 + try {
1.640 + new DocPretty(sw).print(tree.getValue());
1.641 + } catch (IOException e) {
1.642 + // cannot happen
1.643 + }
1.644 + // ignore potential use of entities for now
1.645 + return sw.toString();
1.646 + }
1.647 +
1.648 + private void checkURI(AttributeTree tree, String uri) {
1.649 + try {
1.650 + URI u = new URI(uri);
1.651 + } catch (URISyntaxException e) {
1.652 + env.messages.error(HTML, tree, "dc.invalid.uri", uri);
1.653 + }
1.654 + }
1.655 + // </editor-fold>
1.656 +
1.657 + // <editor-fold defaultstate="collapsed" desc="javadoc tags">
1.658 +
1.659 + @Override
1.660 + public Void visitAuthor(AuthorTree tree, Void ignore) {
1.661 + warnIfEmpty(tree, tree.getName());
1.662 + return super.visitAuthor(tree, ignore);
1.663 + }
1.664 +
1.665 + @Override
1.666 + public Void visitDocRoot(DocRootTree tree, Void ignore) {
1.667 + markEnclosingTag(Flag.HAS_INLINE_TAG);
1.668 + return super.visitDocRoot(tree, ignore);
1.669 + }
1.670 +
1.671 + @Override
1.672 + public Void visitInheritDoc(InheritDocTree tree, Void ignore) {
1.673 + markEnclosingTag(Flag.HAS_INLINE_TAG);
1.674 + // TODO: verify on overridden method
1.675 + foundInheritDoc = true;
1.676 + return super.visitInheritDoc(tree, ignore);
1.677 + }
1.678 +
1.679 + @Override
1.680 + public Void visitLink(LinkTree tree, Void ignore) {
1.681 + markEnclosingTag(Flag.HAS_INLINE_TAG);
1.682 + // simulate inline context on tag stack
1.683 + HtmlTag t = (tree.getKind() == DocTree.Kind.LINK)
1.684 + ? HtmlTag.CODE : HtmlTag.SPAN;
1.685 + tagStack.push(new TagStackItem(tree, t));
1.686 + try {
1.687 + return super.visitLink(tree, ignore);
1.688 + } finally {
1.689 + tagStack.pop();
1.690 + }
1.691 + }
1.692 +
1.693 + @Override
1.694 + public Void visitLiteral(LiteralTree tree, Void ignore) {
1.695 + markEnclosingTag(Flag.HAS_INLINE_TAG);
1.696 + if (tree.getKind() == DocTree.Kind.CODE) {
1.697 + for (TagStackItem tsi: tagStack) {
1.698 + if (tsi.tag == HtmlTag.CODE) {
1.699 + env.messages.warning(HTML, tree, "dc.tag.code.within.code");
1.700 + break;
1.701 + }
1.702 + }
1.703 + }
1.704 + return super.visitLiteral(tree, ignore);
1.705 + }
1.706 +
1.707 + @Override
1.708 + @SuppressWarnings("fallthrough")
1.709 + public Void visitParam(ParamTree tree, Void ignore) {
1.710 + boolean typaram = tree.isTypeParameter();
1.711 + IdentifierTree nameTree = tree.getName();
1.712 + Element paramElement = nameTree != null ? env.trees.getElement(new DocTreePath(getCurrentPath(), nameTree)) : null;
1.713 +
1.714 + if (paramElement == null) {
1.715 + switch (env.currElement.getKind()) {
1.716 + case CLASS: case INTERFACE: {
1.717 + if (!typaram) {
1.718 + env.messages.error(REFERENCE, tree, "dc.invalid.param");
1.719 + break;
1.720 + }
1.721 + }
1.722 + case METHOD: case CONSTRUCTOR: {
1.723 + env.messages.error(REFERENCE, nameTree, "dc.param.name.not.found");
1.724 + break;
1.725 + }
1.726 +
1.727 + default:
1.728 + env.messages.error(REFERENCE, tree, "dc.invalid.param");
1.729 + break;
1.730 + }
1.731 + } else {
1.732 + foundParams.add(paramElement);
1.733 + }
1.734 +
1.735 + warnIfEmpty(tree, tree.getDescription());
1.736 + return super.visitParam(tree, ignore);
1.737 + }
1.738 +
1.739 + private void checkParamsDocumented(List<? extends Element> list) {
1.740 + if (foundInheritDoc)
1.741 + return;
1.742 +
1.743 + for (Element e: list) {
1.744 + if (!foundParams.contains(e)) {
1.745 + CharSequence paramName = (e.getKind() == ElementKind.TYPE_PARAMETER)
1.746 + ? "<" + e.getSimpleName() + ">"
1.747 + : e.getSimpleName();
1.748 + reportMissing("dc.missing.param", paramName);
1.749 + }
1.750 + }
1.751 + }
1.752 +
1.753 + @Override
1.754 + public Void visitReference(ReferenceTree tree, Void ignore) {
1.755 + String sig = tree.getSignature();
1.756 + if (sig.contains("<") || sig.contains(">"))
1.757 + env.messages.error(REFERENCE, tree, "dc.type.arg.not.allowed");
1.758 +
1.759 + Element e = env.trees.getElement(getCurrentPath());
1.760 + if (e == null)
1.761 + env.messages.error(REFERENCE, tree, "dc.ref.not.found");
1.762 + return super.visitReference(tree, ignore);
1.763 + }
1.764 +
1.765 + @Override
1.766 + public Void visitReturn(ReturnTree tree, Void ignore) {
1.767 + Element e = env.trees.getElement(env.currPath);
1.768 + if (e.getKind() != ElementKind.METHOD
1.769 + || ((ExecutableElement) e).getReturnType().getKind() == TypeKind.VOID)
1.770 + env.messages.error(REFERENCE, tree, "dc.invalid.return");
1.771 + foundReturn = true;
1.772 + warnIfEmpty(tree, tree.getDescription());
1.773 + return super.visitReturn(tree, ignore);
1.774 + }
1.775 +
1.776 + @Override
1.777 + public Void visitSerialData(SerialDataTree tree, Void ignore) {
1.778 + warnIfEmpty(tree, tree.getDescription());
1.779 + return super.visitSerialData(tree, ignore);
1.780 + }
1.781 +
1.782 + @Override
1.783 + public Void visitSerialField(SerialFieldTree tree, Void ignore) {
1.784 + warnIfEmpty(tree, tree.getDescription());
1.785 + return super.visitSerialField(tree, ignore);
1.786 + }
1.787 +
1.788 + @Override
1.789 + public Void visitSince(SinceTree tree, Void ignore) {
1.790 + warnIfEmpty(tree, tree.getBody());
1.791 + return super.visitSince(tree, ignore);
1.792 + }
1.793 +
1.794 + @Override
1.795 + public Void visitThrows(ThrowsTree tree, Void ignore) {
1.796 + ReferenceTree exName = tree.getExceptionName();
1.797 + Element ex = env.trees.getElement(new DocTreePath(getCurrentPath(), exName));
1.798 + if (ex == null) {
1.799 + env.messages.error(REFERENCE, tree, "dc.ref.not.found");
1.800 + } else if (isThrowable(ex.asType())) {
1.801 + switch (env.currElement.getKind()) {
1.802 + case CONSTRUCTOR:
1.803 + case METHOD:
1.804 + if (isCheckedException(ex.asType())) {
1.805 + ExecutableElement ee = (ExecutableElement) env.currElement;
1.806 + checkThrowsDeclared(exName, ex.asType(), ee.getThrownTypes());
1.807 + }
1.808 + break;
1.809 + default:
1.810 + env.messages.error(REFERENCE, tree, "dc.invalid.throws");
1.811 + }
1.812 + } else {
1.813 + env.messages.error(REFERENCE, tree, "dc.invalid.throws");
1.814 + }
1.815 + warnIfEmpty(tree, tree.getDescription());
1.816 + return scan(tree.getDescription(), ignore);
1.817 + }
1.818 +
1.819 + private boolean isThrowable(TypeMirror tm) {
1.820 + switch (tm.getKind()) {
1.821 + case DECLARED:
1.822 + case TYPEVAR:
1.823 + return env.types.isAssignable(tm, env.java_lang_Throwable);
1.824 + }
1.825 + return false;
1.826 + }
1.827 +
1.828 + private void checkThrowsDeclared(ReferenceTree tree, TypeMirror t, List<? extends TypeMirror> list) {
1.829 + boolean found = false;
1.830 + for (TypeMirror tl : list) {
1.831 + if (env.types.isAssignable(t, tl)) {
1.832 + foundThrows.add(tl);
1.833 + found = true;
1.834 + }
1.835 + }
1.836 + if (!found)
1.837 + env.messages.error(REFERENCE, tree, "dc.exception.not.thrown", t);
1.838 + }
1.839 +
1.840 + private void checkThrowsDocumented(List<? extends TypeMirror> list) {
1.841 + if (foundInheritDoc)
1.842 + return;
1.843 +
1.844 + for (TypeMirror tl: list) {
1.845 + if (isCheckedException(tl) && !foundThrows.contains(tl))
1.846 + reportMissing("dc.missing.throws", tl);
1.847 + }
1.848 + }
1.849 +
1.850 + @Override
1.851 + public Void visitUnknownBlockTag(UnknownBlockTagTree tree, Void ignore) {
1.852 + checkUnknownTag(tree, tree.getTagName());
1.853 + return super.visitUnknownBlockTag(tree, ignore);
1.854 + }
1.855 +
1.856 + @Override
1.857 + public Void visitUnknownInlineTag(UnknownInlineTagTree tree, Void ignore) {
1.858 + checkUnknownTag(tree, tree.getTagName());
1.859 + return super.visitUnknownInlineTag(tree, ignore);
1.860 + }
1.861 +
1.862 + private void checkUnknownTag(DocTree tree, String tagName) {
1.863 + if (env.customTags != null && !env.customTags.contains(tagName))
1.864 + env.messages.error(SYNTAX, tree, "dc.tag.unknown", tagName);
1.865 + }
1.866 +
1.867 + @Override
1.868 + public Void visitValue(ValueTree tree, Void ignore) {
1.869 + ReferenceTree ref = tree.getReference();
1.870 + if (ref == null || ref.getSignature().isEmpty()) {
1.871 + if (!isConstant(env.currElement))
1.872 + env.messages.error(REFERENCE, tree, "dc.value.not.allowed.here");
1.873 + } else {
1.874 + Element e = env.trees.getElement(new DocTreePath(getCurrentPath(), ref));
1.875 + if (!isConstant(e))
1.876 + env.messages.error(REFERENCE, tree, "dc.value.not.a.constant");
1.877 + }
1.878 +
1.879 + markEnclosingTag(Flag.HAS_INLINE_TAG);
1.880 + return super.visitValue(tree, ignore);
1.881 + }
1.882 +
1.883 + private boolean isConstant(Element e) {
1.884 + if (e == null)
1.885 + return false;
1.886 +
1.887 + switch (e.getKind()) {
1.888 + case FIELD:
1.889 + Object value = ((VariableElement) e).getConstantValue();
1.890 + return (value != null); // can't distinguish "not a constant" from "constant is null"
1.891 + default:
1.892 + return false;
1.893 + }
1.894 + }
1.895 +
1.896 + @Override
1.897 + public Void visitVersion(VersionTree tree, Void ignore) {
1.898 + warnIfEmpty(tree, tree.getBody());
1.899 + return super.visitVersion(tree, ignore);
1.900 + }
1.901 +
1.902 + @Override
1.903 + public Void visitErroneous(ErroneousTree tree, Void ignore) {
1.904 + env.messages.error(SYNTAX, tree, null, tree.getDiagnostic().getMessage(null));
1.905 + return null;
1.906 + }
1.907 + // </editor-fold>
1.908 +
1.909 + // <editor-fold defaultstate="collapsed" desc="Utility methods">
1.910 +
1.911 + private boolean isCheckedException(TypeMirror t) {
1.912 + return !(env.types.isAssignable(t, env.java_lang_Error)
1.913 + || env.types.isAssignable(t, env.java_lang_RuntimeException));
1.914 + }
1.915 +
1.916 + private boolean isSynthetic() {
1.917 + switch (env.currElement.getKind()) {
1.918 + case CONSTRUCTOR:
1.919 + // A synthetic default constructor has the same pos as the
1.920 + // enclosing class
1.921 + TreePath p = env.currPath;
1.922 + return env.getPos(p) == env.getPos(p.getParentPath());
1.923 + }
1.924 + return false;
1.925 + }
1.926 +
1.927 + void markEnclosingTag(Flag flag) {
1.928 + TagStackItem top = tagStack.peek();
1.929 + if (top != null)
1.930 + top.flags.add(flag);
1.931 + }
1.932 +
1.933 + String toString(TreePath p) {
1.934 + StringBuilder sb = new StringBuilder("TreePath[");
1.935 + toString(p, sb);
1.936 + sb.append("]");
1.937 + return sb.toString();
1.938 + }
1.939 +
1.940 + void toString(TreePath p, StringBuilder sb) {
1.941 + TreePath parent = p.getParentPath();
1.942 + if (parent != null) {
1.943 + toString(parent, sb);
1.944 + sb.append(",");
1.945 + }
1.946 + sb.append(p.getLeaf().getKind()).append(":").append(env.getPos(p)).append(":S").append(env.getStartPos(p));
1.947 + }
1.948 +
1.949 + void warnIfEmpty(DocTree tree, List<? extends DocTree> list) {
1.950 + for (DocTree d: list) {
1.951 + switch (d.getKind()) {
1.952 + case TEXT:
1.953 + if (hasNonWhitespace((TextTree) d))
1.954 + return;
1.955 + break;
1.956 + default:
1.957 + return;
1.958 + }
1.959 + }
1.960 + env.messages.warning(SYNTAX, tree, "dc.empty", tree.getKind().tagName);
1.961 + }
1.962 +
1.963 + boolean hasNonWhitespace(TextTree tree) {
1.964 + String s = tree.getBody();
1.965 + for (int i = 0; i < s.length(); i++) {
1.966 + if (!Character.isWhitespace(s.charAt(i)))
1.967 + return true;
1.968 + }
1.969 + return false;
1.970 + }
1.971 +
1.972 + // </editor-fold>
1.973 +
1.974 +}
