8073100: [javadoc] Provide an ability to suppress document generation for specific elements

Reviewed-by: jjg

langtools/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTree.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -101,6 +101,12 @@ public interface DocTree {
          */
         EXCEPTION("exception"),
 
+        /**
+         * Used for instances of {@link HiddenTree}
+         * representing an @hidden tag.
+         */
+        HIDDEN("hidden"),
+
         /**
          * Used for instances of {@link IdentifierTree}
          * representing an identifier.
@@ -108,7 +114,7 @@ public interface DocTree {
         IDENTIFIER,
 
         /**
-         * Used for instances of {@index term optional-descr}
+         * Used for instances of {@link IndexTree}
          * representing a search term.
          */
         INDEX("index"),

langtools/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -128,6 +128,14 @@ public interface DocTreeVisitor<R,P> {
      */
     R visitErroneous(ErroneousTree node, P p);
 
+    /**
+     * Visits a HiddenTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
+    R visitHidden(HiddenTree node, P p);
+
     /**
      * Visits an IdentifierTree node.
      * @param node the node being visited

langtools/src/jdk.compiler/share/classes/com/sun/source/doctree/HiddenTree.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package com.sun.source.doctree;
+
+import java.util.List;
+
+/**
+ *
+ * A tree node for an @hidden block tag.
+ *
+ * <p>
+ * &#064;hidden
+ *
+ * @since 1.9
+ */
+public interface HiddenTree extends BlockTagTree {
+    /**
+     * Returns the description explaining why an item is hidden.
+     * @return the description
+     */
+    List<? extends DocTree> getBody();
+}

langtools/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java

@@ -42,6 +42,7 @@ import com.sun.source.doctree.DocTree;
 import com.sun.source.doctree.EndElementTree;
 import com.sun.source.doctree.EntityTree;
 import com.sun.source.doctree.ErroneousTree;
+import com.sun.source.doctree.HiddenTree;
 import com.sun.source.doctree.IdentifierTree;
 import com.sun.source.doctree.IndexTree;
 import com.sun.source.doctree.InheritDocTree;
@@ -155,6 +156,13 @@ public interface DocTreeFactory {
      */
     ThrowsTree newExceptionTree(ReferenceTree name, List<? extends DocTree> description);
 
+    /**
+     * Create a new {@code HiddenTree} object, to represent an {@code {@hidden } } tag.
+     * @param text the content of the tag
+     * @return a {@code HiddenTree} object
+     */
+    HiddenTree newHiddenTree(List<? extends DocTree> text);
+
     /**
      * Create a new {@code IdentifierTree} object, to represent an identifier, such as in a
      * {@code @param } tag.

langtools/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -235,6 +235,18 @@ public class DocTreeScanner<R,P> implements DocTreeVisitor<R,P> {
         return null;
     }
 
+    /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
+    @Override
+    public R visitHidden(HiddenTree node, P p) {
+        return scan(node.getBody(), p);
+    }
+
     /**
      * {@inheritDoc} This implementation returns {@code null}.
      *

langtools/src/jdk.compiler/share/classes/com/sun/source/util/SimpleDocTreeVisitor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -203,6 +203,17 @@ public class SimpleDocTreeVisitor<R,P> implements DocTreeVisitor<R, P> {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return the result of {@code defaultAction}
+     */
+    public R visitHidden(HiddenTree node, P p) {
+        return defaultAction(node, p);
+    }
+
     /**
      * {@inheritDoc} This implementation calls {@code defaultAction}.
      *

langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java

@@ -30,6 +30,7 @@ import java.util.HashMap;
 import java.util.Map;
 
 import com.sun.source.doctree.AttributeTree.ValueKind;
+import com.sun.source.doctree.DocTree;
 import com.sun.tools.javac.parser.DocCommentParser.TagParser.Kind;
 import com.sun.tools.javac.parser.Tokens.Comment;
 import com.sun.tools.javac.parser.Tokens.TokenKind;
@@ -1064,6 +1065,14 @@ public class DocCommentParser {
                 }
             },
 
+            // @hidden hidden-text
+            new TagParser(Kind.BLOCK, DCTree.Kind.HIDDEN) {
+                public DCTree parse(int pos) {
+                    List<DCTree> reason = blockContent();
+                    return m.at(pos).newHiddenTree(reason);
+                }
+            },
+
             // @index search-term options-description
             new TagParser(Kind.INLINE, DCTree.Kind.INDEX) {
                 public DCTree parse(int pos) throws ParseException {

langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DCTree.java

@@ -390,6 +390,29 @@ public abstract class DCTree implements DocTree {
 
     }
 
+    public static class DCHidden extends DCBlockTag implements HiddenTree {
+        public final List<DCTree> body;
+
+        DCHidden(List<DCTree> body) {
+            this.body = body;
+        }
+
+        @Override @DefinedBy(Api.COMPILER_TREE)
+        public Kind getKind() {
+            return Kind.HIDDEN;
+        }
+
+        @Override @DefinedBy(Api.COMPILER_TREE)
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitHidden(this, d);
+        }
+
+        @Override @DefinedBy(Api.COMPILER_TREE)
+        public List<? extends DocTree> getBody() {
+            return body;
+        }
+    }
+
     public static class DCIdentifier extends DCTree implements IdentifierTree {
         public final Name name;
 

langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocPretty.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -259,6 +259,20 @@ public class DocPretty implements DocTreeVisitor<Void,Void> {
         return null;
     }
 
+    @DefinedBy(Api.COMPILER_TREE)
+    public Void visitHidden(HiddenTree node, Void p) {
+        try {
+            printTagName(node);
+            if (!node.getBody().isEmpty()) {
+                print(" ");
+                print(node.getBody());
+            }
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
     @DefinedBy(Api.COMPILER_TREE)
     public Void visitIdentifier(IdentifierTree node, Void p) {
         try {

langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java

@@ -60,6 +60,7 @@ import com.sun.tools.javac.tree.DCTree.DCDocRoot;
 import com.sun.tools.javac.tree.DCTree.DCEndElement;
 import com.sun.tools.javac.tree.DCTree.DCEntity;
 import com.sun.tools.javac.tree.DCTree.DCErroneous;
+import com.sun.tools.javac.tree.DCTree.DCHidden;
 import com.sun.tools.javac.tree.DCTree.DCIdentifier;
 import com.sun.tools.javac.tree.DCTree.DCIndex;
 import com.sun.tools.javac.tree.DCTree.DCInheritDoc;
@@ -277,6 +278,13 @@ public class DocTreeMaker implements DocTreeFactory {
         return tree;
     }
 
+    @Override @DefinedBy(Api.COMPILER_TREE)
+    public DCHidden newHiddenTree(List<? extends DocTree> text) {
+        DCHidden tree = new DCHidden(cast(text));
+        tree.pos = pos;
+        return tree;
+    }
+
     @Override @DefinedBy(Api.COMPILER_TREE)
     public DCIdentifier newIdentifierTree(Name name) {
         DCIdentifier tree = new DCIdentifier(name);

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java

@@ -230,7 +230,8 @@ public class HtmlDoclet extends AbstractDoclet {
             klass = iterator.next();
             TypeElement next = iterator.nextIndex() == list.size()
                     ? null : list.get(iterator.nextIndex());
-            if (!(configuration.isGeneratedDoc(klass) && utils.isIncluded(klass))) {
+            if (utils.isHidden(klass) ||
+                    !(configuration.isGeneratedDoc(klass) && utils.isIncluded(klass))) {
                 continue;
             }
             try {

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties

@@ -133,6 +133,7 @@ doclet.Property_Detail=Property Detail
 doclet.Method_Detail=Method Detail
 doclet.Constructor_Detail=Constructor Detail
 doclet.Deprecated=Deprecated.
+doclet.Hidden=Hidden
 doclet.Groupname_already_used=In -group option, groupname already used: {0}
 doclet.value_tag_invalid_reference={0} (referenced by @value tag) is an unknown reference.
 doclet.value_tag_invalid_constant=@value tag (which references {0}) can only be used in constants.

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/HiddenTaglet.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package jdk.javadoc.internal.doclets.toolkit.taglets;
+
+import javax.lang.model.element.Element;
+
+import jdk.javadoc.internal.doclets.toolkit.Content;
+
+import static com.sun.source.doctree.DocTree.Kind.*;
+
+/**
+ * A taglet that represents the @hidden tag.
+ *
+ *  <p><b>This is NOT part of any supported API.
+ *  If you write code that depends on this, you do so at your own risk.
+ *  This code and its internal interfaces are subject to change or
+ *  deletion without notice.</b>
+ */
+
+public class HiddenTaglet extends BaseTaglet{
+
+    public HiddenTaglet() {
+        name = HIDDEN.tagName;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public Content getTagletOutput(Element holder, TagletWriter writer) {
+        return writer.deprecatedTagOutput(holder);
+    }
+}
+

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java

@@ -685,15 +685,17 @@ public class TagletManager {
         addStandardTaglet(new SimpleTaglet(EXCEPTION.tagName, null,
                 SimpleTaglet.METHOD + SimpleTaglet.CONSTRUCTOR));
         addStandardTaglet(!nosince, new SimpleTaglet(SINCE.tagName, message.getText("doclet.Since"),
-               SimpleTaglet.ALL));
+                SimpleTaglet.ALL));
         addStandardTaglet(showversion, new SimpleTaglet(VERSION.tagName, message.getText("doclet.Version"),
                 SimpleTaglet.PACKAGE + SimpleTaglet.TYPE + SimpleTaglet.OVERVIEW));
         addStandardTaglet(showauthor, new SimpleTaglet(AUTHOR.tagName, message.getText("doclet.Author"),
                 SimpleTaglet.PACKAGE + SimpleTaglet.TYPE + SimpleTaglet.OVERVIEW));
         addStandardTaglet(new SimpleTaglet(SERIAL_DATA.tagName, message.getText("doclet.SerialData"),
-            SimpleTaglet.EXCLUDED));
+                SimpleTaglet.EXCLUDED));
+        addStandardTaglet(new SimpleTaglet(HIDDEN.tagName, message.getText("doclet.Hidden"),
+                SimpleTaglet.FIELD + SimpleTaglet.METHOD + SimpleTaglet.TYPE));
         customTags.put((temp = new SimpleTaglet("factory", message.getText("doclet.Factory"),
-            SimpleTaglet.METHOD)).getName(), temp);
+                SimpleTaglet.METHOD)).getName(), temp);
         addStandardTaglet(new SeeTaglet());
         //Standard inline tags
         addStandardTaglet(new DocRootTaglet());

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassTree.java

@@ -170,8 +170,7 @@ public class ClassTree {
                 continue;
             }
 
-            if (configuration.javafx
+            if (utils.isHidden(aClass)) {
-                    && !utils.getBlockTags(aClass, "treatAsPrivate").isEmpty()) {
                 continue;
             }
 

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/IndexBuilder.java

@@ -185,10 +185,8 @@ public class IndexBuilder {
      * Should this element be added to the index map?
      */
     protected boolean shouldAddToIndexMap(Element element) {
-        if (javafx) {
+        if (utils.isHidden(element)) {
-            if (!utils.getBlockTags(element, "treatAsPrivate").isEmpty()) {
+            return false;
-                return false;
-            }
         }
 
         if (utils.isPackage(element))

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java

@@ -85,6 +85,7 @@ import static javax.lang.model.element.Modifier.*;
 import static javax.lang.model.type.TypeKind.*;
 
 import static com.sun.source.doctree.DocTree.Kind.*;
+import com.sun.source.util.SimpleDocTreeVisitor;
 import static jdk.javadoc.internal.doclets.toolkit.builders.ConstantsSummaryBuilder.MAX_CONSTANT_VALUE_INDEX_LENGTH;
 
 
@@ -1231,8 +1232,9 @@ public class Utils {
             superType = getObjectType();
         }
         TypeElement superClass = asTypeElement(superType);
-
+        // skip "hidden" classes
-        while (superClass != null && !isPublic(superClass) && !isLinkable(superClass)) {
+        while ((superClass != null && isHidden(superClass))
+                || (superClass != null &&  !isPublic(superClass) && !isLinkable(superClass))) {
             TypeMirror supersuperType = superClass.getSuperclass();
             TypeElement supersuperClass = asTypeElement(supersuperType);
             if (supersuperClass == null
@@ -1447,10 +1449,29 @@ public class Utils {
                 + propertyName.substring(1);
     }
 
+    /**
+     * Returns true if the element is included, contains @hidden tag,
+     * or if javafx flag is present and element contains @treatAsPrivate
+     * tag.
+     * @param e the queried element
+     * @return true if it exists, false otherwise
+     */
+    public boolean isHidden(Element e) {
+        // prevent needless tests on elements which are not included
+        if (!isIncluded(e)) {
+            return false;
+        }
+        if (configuration.javafx &&
+                hasBlockTag(e, DocTree.Kind.UNKNOWN_BLOCK_TAG, "treatAsPrivate")) {
+            return true;
+        }
+        return hasBlockTag(e, DocTree.Kind.HIDDEN);
+    }
+
     /**
      * In case of JavaFX mode on, filters out classes that are private,
-     * package private or having the @treatAsPrivate annotation. Those are not
+     * package private, these are not documented in JavaFX mode, also
-     * documented in JavaFX mode.
+     * remove those classes that have @hidden or @treatAsPrivate comment tag.
      *
      * @param classlist a collection of TypeElements
      * @param javafx set to true if in JavaFX mode.
@@ -1462,16 +1483,14 @@ public class Utils {
                 new TreeSet<>(makeGeneralPurposeComparator());
         if (!javafx) {
             for (Element te : classlist) {
-                filteredOutClasses.add((TypeElement)te);
+                if (!isHidden(te)) {
+                    filteredOutClasses.add((TypeElement)te);
+                }
             }
             return filteredOutClasses;
         }
         for (Element e : classlist) {
-            if (isPrivate(e) || isPackagePrivate(e)) {
+            if (isPrivate(e) || isPackagePrivate(e) || isHidden(e)) {
-                continue;
-            }
-            List<? extends DocTree> aspTags = getBlockTags(e, "treatAsPrivate");
-            if (aspTags != null && !aspTags.isEmpty()) {
                 continue;
             }
             filteredOutClasses.add((TypeElement)e);
@@ -2711,6 +2730,7 @@ public class Utils {
         switch (tagName) {
             case "author":
             case "deprecated":
+            case "hidden":
             case "param":
             case "return":
             case "see":
@@ -2734,7 +2754,7 @@ public class Utils {
         List<? extends DocTree> blockTags = getBlockTags(element, kind);
         List<DocTree> out = new ArrayList<>();
         String tname = tagName.startsWith("@") ? tagName.substring(1) : tagName;
-        CommentHelper ch = wksMap.get(element);
+        CommentHelper ch = getCommentHelper(element);
         for (DocTree dt : blockTags) {
             if (ch.getTagName(dt).equals(tname)) {
                 out.add(dt);
@@ -2743,6 +2763,25 @@ public class Utils {
         return out;
     }
 
+    public boolean hasBlockTag(Element element, DocTree.Kind kind) {
+        return hasBlockTag(element, kind, null);
+    }
+
+    public boolean hasBlockTag(Element element, DocTree.Kind kind, final String tagName) {
+        CommentHelper ch = getCommentHelper(element);
+        String tname = tagName != null && tagName.startsWith("@")
+                ? tagName.substring(1)
+                : tagName;
+        for (DocTree dt : getBlockTags(element, kind)) {
+            if (dt.getKind() == kind) {
+                if (tname == null || ch.getTagName(dt).equals(tname)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+
     /**
      * Gets a TreePath for an Element. Note this method is called very
      * frequently, care must be taken to ensure this method is lithe

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/VisibleMemberMap.java

@@ -382,7 +382,7 @@ public class VisibleMemberMap {
                 if (!found(members, element)) {
                     if (memberIsVisible(element)) {
                         if (!isOverridden(element, level)) {
-                            if (!isTreatedAsPrivate(element)) {
+                            if (!utils.isHidden(element)) {
                                 incllist.add(element);
                             }
                         }
@@ -396,16 +396,6 @@ public class VisibleMemberMap {
             fillMemberLevelMap(getClassMembers(fromClass, false), level);
         }
 
-        private boolean isTreatedAsPrivate(Element pgmelem) {
-            if (!configuration.javafx) {
-                return false;
-            }
-
-            List<? extends DocTree> aspTags = utils.getBlockTags(pgmelem, "@treatAsPrivate");
-            boolean result = (aspTags != null) && (!aspTags.isEmpty());
-            return result;
-        }
-
         /**
          * Is given element visible in given typeElement in terms of inheritance? The given element
          * is visible in the given typeElement if it is public or protected and if it is

langtools/test/jdk/javadoc/doclet/testHiddenTag/TestHiddenTag.java

@@ -0,0 +1,103 @@
+/*
+ * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ * @test
+ * @bug 8073100
+ * @summary ensure the hidden tag works as intended
+ * @library ../lib
+ * @modules jdk.javadoc/jdk.javadoc.internal.tool
+ * @build JavadocTester
+ * @run main TestHiddenTag
+ */
+
+public class TestHiddenTag extends JavadocTester {
+
+    public static void main(String... args) throws Exception {
+        TestHiddenTag tester = new TestHiddenTag();
+        tester.runTests();
+    }
+
+
+    /**
+     * Perform tests on @hidden tags
+     */
+    @Test
+    public void test1() {
+        javadoc("-d", "out1",
+                "-sourcepath", testSrc,
+                "-package",
+                "pkg1");
+        checkExit(Exit.OK);
+
+        checkOutput("pkg1/A.html", true,
+                "<a name=\"visibleField\">",
+                "<a name=\"visibleMethod--\">",
+                "<dt>Direct Known Subclasses:</dt>\n" +
+                "<dd><a href=\"../pkg1/A.VisibleInner.html\" title=\"class in pkg1\">" +
+                "A.VisibleInner</a>, <a href=\"../pkg1/A.VisibleInnerExtendsInvisibleInner.html\" " +
+                "title=\"class in pkg1\">A.VisibleInnerExtendsInvisibleInner</a></dd>");
+
+        checkOutput("pkg1/A.html", false,
+                "<a name=\"inVisibleField\">",
+                "<a name=\"inVisibleMethod--\">");
+
+        checkOutput("pkg1/A.VisibleInner.html", true,
+                "<code><a href=\"../pkg1/A.html#visibleField\">visibleField</a></code>",
+                "<code><a href=\"../pkg1/A.html#visibleMethod--\">visibleMethod</a></code>",
+                "<h3>Nested classes/interfaces inherited from class&nbsp;pkg1." +
+                "<a href=\"../pkg1/A.html\" title=\"class in pkg1\">A</a></h3>\n" +
+                "<code><a href=\"../pkg1/A.VisibleInner.html\" title=\"class in pkg1\">" +
+                "A.VisibleInner</a>, <a href=\"../pkg1/A.VisibleInnerExtendsInvisibleInner.html\" " +
+                "title=\"class in pkg1\">A.VisibleInnerExtendsInvisibleInner</a></code></li>\n" +
+                "</ul>");
+
+        checkOutput("pkg1/A.VisibleInner.html", false,
+                "../pkg1/A.VisibleInner.html#VisibleInner--",
+                "<a name=\"inVisibleField\">",
+                "<a name=\"inVisibleMethod--\">");
+
+        checkOutput("pkg1/A.VisibleInnerExtendsInvisibleInner.html", true,
+                "<pre>public static class <span class=\"typeNameLabel\">" +
+                "A.VisibleInnerExtendsInvisibleInner</span>\n" +
+                "extends <a href=\"../pkg1/A.html\" title=\"class in pkg1\">A</a></pre>",
+                "<code><a href=\"../pkg1/A.html#visibleField\">visibleField</a></code></li>",
+                "<code><a href=\"../pkg1/A.html#visibleMethod--\">visibleMethod</a></code>");
+
+        checkOutput("pkg1/A.VisibleInnerExtendsInvisibleInner.html", false,
+                "invisibleField",
+                "invisibleMethod",
+                "A.InvisibleInner");
+
+        checkOutput("pkg1/package-frame.html", false, "A.InvisibleInner");
+
+        checkOutput("pkg1/package-summary.html", false, "A.InvisibleInner");
+
+        checkOutput("pkg1/package-tree.html", false, "A.InvisibleInner");
+
+        checkFiles(false,
+                "pkg1/A.InvisibleInner.html",
+                "pkg1/A.InvisibleInnerExtendsVisibleInner.html");
+
+    }
+}

langtools/test/jdk/javadoc/doclet/testHiddenTag/pkg1/A.java

@@ -0,0 +1,77 @@
+/*
+ * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package pkg1;
+
+public class A {
+    /**
+     * A visible field.
+     */
+    public A visibleField;
+
+    /**
+     * An invisible field.
+     * @hidden
+     */
+    public A invisibleField;
+
+    /**
+     * A visible method.
+     */
+    public void visibleMethod() {}
+
+    /**
+     * An invisible method.
+     * @hidden
+     */
+    public void invisibleMethod() {}
+
+    /**
+     * A visible inner class.
+     */
+    public static class VisibleInner extends A {
+        /**
+         * An invisible constructor
+         * @hidden invisible
+         */
+        public VisibleInner() {}
+    }
+
+    /**
+     * An invisible inner class.
+     * @hidden
+     */
+    public static class InvisibleInner extends A {}
+
+    /**
+     * A visible inner class, extending an invisible class.
+     */
+    public static class VisibleInnerExtendsInvisibleInner extends InvisibleInner {}
+
+    /**
+     * An invisible inner class extending a visible class.
+     * @hidden
+     */
+    public static class InvisibleInnerExtendsVisibleInner extends InvisibleInner {}
+
+}

langtools/test/tools/javac/doctree/DocCommentTester.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -439,6 +439,16 @@ public class DocCommentTester {
                 return null;
             }
 
+            public Void visitHidden(HiddenTree node, Void p) {
+                header(node);
+                indent(+1);
+                print("body", node.getBody());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
             public Void visitIdentifier(IdentifierTree node, Void p) {
                 header(node, compress(node.getName().toString()));
                 return null;

langtools/test/tools/javac/doctree/HiddenTest.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ * @test
+ * @bug 8073100
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @modules jdk.compiler/com.sun.tools.javac.api
+ *          jdk.compiler/com.sun.tools.javac.file
+ *          jdk.compiler/com.sun.tools.javac.tree
+ *          jdk.compiler/com.sun.tools.javac.util
+ * @build DocCommentTester
+ * @run main DocCommentTester HiddenTest.java
+ */
+
+class HiddenTest {
+    /**
+     * @hidden
+     */
+    void hidden() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    Hidden[HIDDEN, pos:1
+      body: empty
+    ]
+]
+*/
+
+    /**
+     * @hidden text
+     */
+    void hidden_text() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    Hidden[HIDDEN, pos:1
+      body: 1
+        Text[TEXT, pos:9, text]
+    ]
+]
+*/
+
+}

langtools/test/tools/javac/lib/DPrinter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -1044,6 +1044,11 @@ public class DPrinter {
             return visitTree(node, null);
         }
 
+        public Void visitHidden(HiddenTree node, Void p) {
+            printList("body", node.getBody());
+            return visitBlockTag(node, null);
+        }
+
         public Void visitIdentifier(IdentifierTree node, Void p) {
             printName("name", node.getName());
             return visitTree(node, null);