jjg@1455: /* jjg@1495: * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved. jjg@1455: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. jjg@1455: * jjg@1455: * This code is free software; you can redistribute it and/or modify it jjg@1455: * under the terms of the GNU General Public License version 2 only, as jjg@1455: * published by the Free Software Foundation. Oracle designates this jjg@1455: * particular file as subject to the "Classpath" exception as provided jjg@1455: * by Oracle in the LICENSE file that accompanied this code. jjg@1455: * jjg@1455: * This code is distributed in the hope that it will be useful, but WITHOUT jjg@1455: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or jjg@1455: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License jjg@1455: * version 2 for more details (a copy is included in the LICENSE file that jjg@1455: * accompanied this code). jjg@1455: * jjg@1455: * You should have received a copy of the GNU General Public License version jjg@1455: * 2 along with this work; if not, write to the Free Software Foundation, jjg@1455: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. jjg@1455: * jjg@1455: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA jjg@1455: * or visit www.oracle.com if you need additional information or have any jjg@1455: * questions. jjg@1455: */ jjg@1455: jjg@1455: package com.sun.tools.doclint; jjg@1455: jjg@1499: import com.sun.source.doctree.LiteralTree; jjg@1455: import java.util.regex.Matcher; jjg@1455: import com.sun.source.doctree.LinkTree; jjg@1455: import java.net.URI; jjg@1455: import java.util.regex.Pattern; jjg@1455: import java.io.IOException; jjg@1455: import com.sun.tools.javac.tree.DocPretty; jjg@1455: import java.io.StringWriter; jjg@1455: import java.util.Deque; jjg@1455: import java.util.EnumSet; jjg@1455: import java.util.HashSet; jjg@1455: import java.util.LinkedList; jjg@1455: import java.util.List; jjg@1455: import java.util.Set; jjg@1455: jjg@1455: import javax.lang.model.element.Element; jjg@1455: import javax.lang.model.element.ElementKind; jjg@1455: import javax.lang.model.element.ExecutableElement; jjg@1455: import javax.lang.model.element.Name; jjg@1455: import javax.lang.model.element.TypeElement; jjg@1455: import javax.lang.model.type.TypeKind; jjg@1455: import javax.lang.model.type.TypeMirror; jjg@1455: import javax.tools.Diagnostic.Kind; jjg@1455: jjg@1455: import com.sun.source.doctree.AttributeTree; jjg@1455: import com.sun.source.doctree.AuthorTree; jjg@1455: import com.sun.source.doctree.DocCommentTree; jjg@1455: import com.sun.source.doctree.DocTree; jjg@1455: import com.sun.source.doctree.EndElementTree; jjg@1455: import com.sun.source.doctree.EntityTree; jjg@1455: import com.sun.source.doctree.ErroneousTree; jjg@1455: import com.sun.source.doctree.IdentifierTree; jjg@1455: import com.sun.source.doctree.InheritDocTree; jjg@1455: import com.sun.source.doctree.ParamTree; jjg@1455: import com.sun.source.doctree.ReferenceTree; jjg@1455: import com.sun.source.doctree.ReturnTree; jjg@1455: import com.sun.source.doctree.SerialDataTree; jjg@1455: import com.sun.source.doctree.SerialFieldTree; jjg@1455: import com.sun.source.doctree.SinceTree; jjg@1455: import com.sun.source.doctree.StartElementTree; jjg@1455: import com.sun.source.doctree.TextTree; jjg@1455: import com.sun.source.doctree.ThrowsTree; jjg@1455: import com.sun.source.doctree.VersionTree; jjg@1455: import com.sun.source.util.DocTreeScanner; jjg@1455: import com.sun.source.util.TreePath; jjg@1455: import com.sun.tools.doclint.HtmlTag.AttrKind; jjg@1455: import java.net.URISyntaxException; jjg@1455: import static com.sun.tools.doclint.Messages.Group.*; jjg@1455: jjg@1455: jjg@1455: /** jjg@1455: * Validate a doc comment. jjg@1455: * jjg@1455: *
This is NOT part of any supported API. jjg@1455: * If you write code that depends on this, you do so at your own jjg@1455: * risk. This code and its internal interfaces are subject to change jjg@1455: * or deletion without notice.
jjg@1455: */ jjg@1455: public class Checker extends DocTreeScannerinside
jjg@1455: case P: jjg@1455: TagStackItem top = tagStack.peek(); jjg@1455: if (top != null && top.tag == HtmlTag.PRE) jjg@1455: env.messages.warning(HTML, tree, "dc.tag.p.in.pre"); jjg@1455: break; jjg@1455: } jjg@1455: jjg@1455: // check that only block tags and inline tags are used, jjg@1455: // and that blocks tags are not used within inline tags jjg@1455: switch (t.blockType) { jjg@1455: case INLINE: jjg@1455: break; jjg@1455: case BLOCK: jjg@1455: TagStackItem top = tagStack.peek(); jjg@1455: if (top != null && top.tag != null && top.tag.blockType == HtmlTag.BlockType.INLINE) { jjg@1455: switch (top.tree.getKind()) { jjg@1455: case START_ELEMENT: { jjg@1455: Name name = ((StartElementTree) top.tree).getName(); jjg@1455: env.messages.error(HTML, tree, "dc.tag.not.allowed.inline.element", jjg@1455: treeName, name); jjg@1455: break; jjg@1455: } jjg@1455: case LINK: jjg@1455: case LINK_PLAIN: { jjg@1455: String name = top.tree.getKind().tagName; jjg@1455: env.messages.error(HTML, tree, "dc.tag.not.allowed.inline.tag", jjg@1455: treeName, name); jjg@1455: break; jjg@1455: } jjg@1455: default: jjg@1455: env.messages.error(HTML, tree, "dc.tag.not.allowed.inline.other", jjg@1455: treeName); jjg@1455: } jjg@1455: } jjg@1455: break; jjg@1455: case OTHER: jjg@1455: env.messages.error(HTML, tree, "dc.tag.not.allowed", treeName); jjg@1455: break; jjg@1455: default: jjg@1455: throw new AssertionError(); jjg@1455: } jjg@1455: jjg@1455: if (t.flags.contains(HtmlTag.Flag.NO_NEST)) { jjg@1455: for (TagStackItem i: tagStack) { jjg@1455: if (t == i.tag) { jjg@1455: env.messages.warning(HTML, tree, "dc.tag.nested.not.allowed", treeName); jjg@1455: break; jjg@1455: } jjg@1455: } jjg@1455: } jjg@1455: } jjg@1455: jjg@1455: // check for self closing tags, such as jjg@1455: if (tree.isSelfClosing()) { jjg@1455: env.messages.error(HTML, tree, "dc.tag.self.closing", treeName); jjg@1455: } jjg@1455: jjg@1455: try { jjg@1455: TagStackItem parent = tagStack.peek(); jjg@1455: TagStackItem top = new TagStackItem(tree, t); jjg@1455: tagStack.push(top); jjg@1455: jjg@1455: super.visitStartElement(tree, ignore); jjg@1455: jjg@1455: // handle attributes that may or may not have been found in start element jjg@1455: if (t != null) { jjg@1455: switch (t) { jjg@1455: case CAPTION: jjg@1455: if (parent != null && parent.tag == HtmlTag.TABLE) jjg@1455: parent.flags.add(Flag.TABLE_HAS_CAPTION); jjg@1455: break; jjg@1455: jjg@1455: case IMG: jjg@1455: if (!top.attrs.contains(HtmlTag.Attr.ALT)) jjg@1455: env.messages.error(ACCESSIBILITY, tree, "dc.no.alt.attr.for.image"); jjg@1455: break; jjg@1455: } jjg@1455: } jjg@1455: jjg@1455: return null; jjg@1455: } finally { jjg@1455: jjg@1455: if (t == null || t.endKind == HtmlTag.EndKind.NONE) jjg@1455: tagStack.pop(); jjg@1455: } jjg@1455: } jjg@1455: jjg@1455: private void checkHeader(StartElementTree tree, HtmlTag tag) { jjg@1455: // verify the new tag jjg@1455: if (getHeaderLevel(tag) > getHeaderLevel(currHeaderTag) + 1) { jjg@1455: if (currHeaderTag == null) { jjg@1455: env.messages.error(ACCESSIBILITY, tree, "dc.tag.header.sequence.1", tag); jjg@1455: } else { jjg@1455: env.messages.error(ACCESSIBILITY, tree, "dc.tag.header.sequence.2", jjg@1455: tag, currHeaderTag); jjg@1455: } jjg@1455: } jjg@1455: jjg@1455: currHeaderTag = tag; jjg@1455: } jjg@1455: jjg@1455: private int getHeaderLevel(HtmlTag tag) { jjg@1455: if (tag == null) jjg@1455: return 0; jjg@1455: switch (tag) { jjg@1455: case H1: return 1; jjg@1455: case H2: return 2; jjg@1455: case H3: return 3; jjg@1455: case H4: return 4; jjg@1455: case H5: return 5; jjg@1455: case H6: return 6; jjg@1455: default: throw new IllegalArgumentException(); jjg@1455: } jjg@1455: } jjg@1455: jjg@1455: @Override jjg@1455: public Void visitEndElement(EndElementTree tree, Void ignore) { jjg@1455: final Name treeName = tree.getName(); jjg@1455: final HtmlTag t = HtmlTag.get(treeName); jjg@1455: if (t == null) { jjg@1455: env.messages.error(HTML, tree, "dc.tag.unknown", treeName); jjg@1455: } else if (t.endKind == HtmlTag.EndKind.NONE) { jjg@1455: env.messages.error(HTML, tree, "dc.tag.end.not.permitted", treeName); jjg@1455: } else { jjg@1499: boolean done = false; jjg@1455: while (!tagStack.isEmpty()) { jjg@1455: TagStackItem top = tagStack.peek(); jjg@1455: if (t == top.tag) { jjg@1455: switch (t) { jjg@1455: case TABLE: jjg@1455: if (!top.attrs.contains(HtmlTag.Attr.SUMMARY) jjg@1455: && !top.flags.contains(Flag.TABLE_HAS_CAPTION)) { jjg@1455: env.messages.error(ACCESSIBILITY, tree, jjg@1455: "dc.no.summary.or.caption.for.table"); jjg@1455: } jjg@1455: } jjg@1455: if (t.flags.contains(HtmlTag.Flag.EXPECT_CONTENT) jjg@1455: && !top.flags.contains(Flag.HAS_TEXT) jjg@1455: && !top.flags.contains(Flag.HAS_ELEMENT)) { jjg@1455: env.messages.warning(HTML, tree, "dc.tag.empty", treeName); jjg@1455: } jjg@1455: if (t.flags.contains(HtmlTag.Flag.NO_TEXT) jjg@1455: && top.flags.contains(Flag.HAS_TEXT)) { jjg@1455: env.messages.error(HTML, tree, "dc.text.not.allowed", treeName); jjg@1455: } jjg@1455: tagStack.pop(); jjg@1499: done = true; jjg@1455: break; jjg@1455: } else if (top.tag == null || top.tag.endKind != HtmlTag.EndKind.REQUIRED) { jjg@1455: tagStack.pop(); jjg@1455: } else { jjg@1455: boolean found = false; jjg@1455: for (TagStackItem si: tagStack) { jjg@1455: if (si.tag == t) { jjg@1455: found = true; jjg@1455: break; jjg@1455: } jjg@1455: } jjg@1455: if (found && top.tree.getKind() == DocTree.Kind.START_ELEMENT) { jjg@1455: env.messages.error(HTML, top.tree, "dc.tag.start.unmatched", jjg@1455: ((StartElementTree) top.tree).getName()); jjg@1455: tagStack.pop(); jjg@1455: } else { jjg@1455: env.messages.error(HTML, tree, "dc.tag.end.unexpected", treeName); jjg@1499: done = true; jjg@1455: break; jjg@1455: } jjg@1455: } jjg@1455: } jjg@1499: jjg@1499: if (!done && tagStack.isEmpty()) { jjg@1499: env.messages.error(HTML, tree, "dc.tag.end.unexpected", treeName); jjg@1499: } jjg@1455: } jjg@1455: jjg@1455: return super.visitEndElement(tree, ignore); jjg@1455: } jjg@1455: //