changeset 1723:d918b63a5509

8008768: Using {@inheritDoc} in simple tag defined via -tag fails Reviewed-by: jjg, mduigou Contributed-by: jonathan.gibbons@oracle.com, mike.duigou@oracle.com
author jjg
date Fri, 03 May 2013 17:44:38 -0700
parents a2889739cf21
children e8987ce7fb4b
files src/share/classes/com/sun/tools/doclets/formats/html/HtmlDocletWriter.java src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/InheritDocTaglet.java src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ParamTaglet.java src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ReturnTaglet.java src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/SeeTaglet.java src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/SimpleTaglet.java src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ThrowsTaglet.java src/share/classes/com/sun/tools/doclets/internal/toolkit/util/DocFinder.java test/com/sun/javadoc/InheritDocForUserTags/DocTest.java test/com/sun/javadoc/testSimpleTagInherit/TestSimpleTagInherit.java test/com/sun/javadoc/testSimpleTagInherit/p/BaseClass.java test/com/sun/javadoc/testSimpleTagInherit/p/TestClass.java
diffstat 12 files changed, 554 insertions(+), 93 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/com/sun/tools/doclets/formats/html/HtmlDocletWriter.java	Fri May 03 15:08:47 2013 -0700
+++ b/src/share/classes/com/sun/tools/doclets/formats/html/HtmlDocletWriter.java	Fri May 03 17:44:38 2013 -0700
@@ -1497,7 +1497,7 @@
      * @param htmltree the content tree to which the comment will be added
      */
     public void addInlineComment(Doc doc, Tag tag, Content htmltree) {
-        addCommentTags(doc, tag.inlineTags(), false, false, htmltree);
+        addCommentTags(doc, tag, tag.inlineTags(), false, false, htmltree);
     }
 
     /**
@@ -1557,11 +1557,26 @@
      */
     private void addCommentTags(Doc doc, Tag[] tags, boolean depr,
             boolean first, Content htmltree) {
+        addCommentTags(doc, null, tags, depr, first, htmltree);
+    }
+
+    /**
+     * Adds the comment tags.
+     *
+     * @param doc the doc for which the comment tags will be generated
+     * @param holderTag the block tag context for the inline tags
+     * @param tags the first sentence tags for the doc
+     * @param depr true if it is deprecated
+     * @param first true if the first sentence tags should be added
+     * @param htmltree the documentation tree to which the comment tags will be added
+     */
+    private void addCommentTags(Doc doc, Tag holderTag, Tag[] tags, boolean depr,
+            boolean first, Content htmltree) {
         if(configuration.nocomment){
             return;
         }
         Content div;
-        Content result = new RawHtml(commentTagsToString(null, doc, tags, first));
+        Content result = new RawHtml(commentTagsToString(holderTag, doc, tags, first));
         if (depr) {
             Content italic = HtmlTree.I(result);
             div = HtmlTree.DIV(HtmlStyle.block, italic);
--- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/InheritDocTaglet.java	Fri May 03 15:08:47 2013 -0700
+++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/InheritDocTaglet.java	Fri May 03 17:44:38 2013 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 2013, 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
@@ -60,8 +60,8 @@
 
     /**
      * Will return false because this inline tag may
-     * only appear in Methods.
-     * @return false since this is not a method.
+     * not appear in Fields.
+     * @return false
      */
     public boolean inField() {
         return false;
@@ -69,8 +69,8 @@
 
     /**
      * Will return false because this inline tag may
-     * only appear in Methods.
-     * @return false since this is not a method.
+     * not appear in Constructors.
+     * @return false
      */
     public boolean inConstructor() {
         return false;
@@ -78,8 +78,8 @@
 
     /**
      * Will return false because this inline tag may
-     * only appear in Methods.
-     * @return false since this is not a method.
+     * not appear in Overview.
+     * @return false
      */
     public boolean inOverview() {
         return false;
@@ -87,20 +87,20 @@
 
     /**
      * Will return false because this inline tag may
-     * only appear in Methods.
-     * @return false since this is not a method.
+     * not appear in Packages.
+     * @return false
      */
     public boolean inPackage() {
         return false;
     }
 
     /**
-     * Will return false because this inline tag may
-     * only appear in Methods.
-     * @return false since this is not a method.
+     * Will return true because this inline tag may
+     * appear in Type (Class).
+     * @return true
      */
     public boolean inType() {
-        return false;
+        return true;
     }
 
     /**
@@ -109,12 +109,13 @@
      * of @inheritDoc with documentation from it's superclass or superinterface.
      *
      * @param writer the writer that is writing the output.
-     * @param md the {@link MethodDoc} that we are documenting.
-     * @param holderTag the tag that holds the inheritDoc tag.
+     * @param ped the {@link ProgramElementDoc} that we are documenting.
+     * @param holderTag the tag that holds the inheritDoc tag or null for type
+     * (class) docs.
      * @param isFirstSentence true if we only want to inherit the first sentence.
      */
     private TagletOutput retrieveInheritedDocumentation(TagletWriter writer,
-            MethodDoc md, Tag holderTag, boolean isFirstSentence) {
+            ProgramElementDoc ped, Tag holderTag, boolean isFirstSentence) {
         TagletOutput replacement = writer.getTagletOutputInstance();
 
         Configuration configuration = writer.configuration();
@@ -122,20 +123,30 @@
             null : configuration.tagletManager.getTaglet(holderTag.name());
         if (inheritableTaglet != null &&
             !(inheritableTaglet instanceof InheritableTaglet)) {
+                String message = ped.name() +
+                    ((ped instanceof ExecutableMemberDoc)
+                        ? ((ExecutableMemberDoc)ped).flatSignature()
+                        : "");
                 //This tag does not support inheritence.
-                configuration.message.warning(md.position(),
-                "doclet.noInheritedDoc", md.name() + md.flatSignature());
+                configuration.message.warning(ped.position(),
+                "doclet.noInheritedDoc", message);
          }
         DocFinder.Output inheritedDoc =
-            DocFinder.search(new DocFinder.Input(md,
+            DocFinder.search(new DocFinder.Input(ped,
                 (InheritableTaglet) inheritableTaglet, holderTag,
                 isFirstSentence, true));
-        if (inheritedDoc.isValidInheritDocTag == false) {
-            configuration.message.warning(md.position(),
-                "doclet.noInheritedDoc", md.name() + md.flatSignature());
-        } else if (inheritedDoc.inlineTags.length > 0) {
-            replacement = writer.commentTagsToOutput(inheritedDoc.holderTag,
-                inheritedDoc.holder, inheritedDoc.inlineTags, isFirstSentence);
+        if (inheritedDoc.isValidInheritDocTag) {
+            if (inheritedDoc.inlineTags.length > 0) {
+                replacement = writer.commentTagsToOutput(inheritedDoc.holderTag,
+                    inheritedDoc.holder, inheritedDoc.inlineTags, isFirstSentence);
+            }
+        } else {
+            String message = ped.name() +
+                    ((ped instanceof ExecutableMemberDoc)
+                        ? ((ExecutableMemberDoc)ped).flatSignature()
+                        : "");
+            configuration.message.warning(ped.position(),
+                "doclet.noInheritedDoc", message);
         }
         return replacement;
     }
@@ -149,11 +160,11 @@
      * @return the TagletOutput representation of this <code>Tag</code>.
      */
     public TagletOutput getTagletOutput(Tag tag, TagletWriter tagletWriter) {
-        if (! (tag.holder() instanceof MethodDoc)) {
+        if (! (tag.holder() instanceof ProgramElementDoc)) {
             return tagletWriter.getOutputInstance();
         }
         return tag.name().equals("@inheritDoc") ?
-                retrieveInheritedDocumentation(tagletWriter, (MethodDoc) tag.holder(), null, tagletWriter.isFirstSentence) :
-                retrieveInheritedDocumentation(tagletWriter, (MethodDoc) tag.holder(), tag, tagletWriter.isFirstSentence);
+                retrieveInheritedDocumentation(tagletWriter, (ProgramElementDoc) tag.holder(), null, tagletWriter.isFirstSentence) :
+                retrieveInheritedDocumentation(tagletWriter, (ProgramElementDoc) tag.holder(), tag, tagletWriter.isFirstSentence);
     }
 }
--- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ParamTaglet.java	Fri May 03 15:08:47 2013 -0700
+++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ParamTaglet.java	Fri May 03 17:44:38 2013 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 2013, 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,14 +101,14 @@
             }
         }
         ParamTag[] tags = input.isTypeVariableParamTag ?
-            input.method.typeParamTags() : input.method.paramTags();
+            ((MethodDoc)input.element).typeParamTags() : ((MethodDoc)input.element).paramTags();
         Map<String, String> rankMap = getRankMap(input.isTypeVariableParamTag ?
-            (Object[]) input.method.typeParameters() :
-            (Object[]) input.method.parameters());
+            (Object[]) ((MethodDoc)input.element).typeParameters() :
+            (Object[]) ((MethodDoc)input.element).parameters());
         for (int i = 0; i < tags.length; i++) {
             if (rankMap.containsKey(tags[i].parameterName()) &&
                     rankMap.get(tags[i].parameterName()).equals((input.tagId))) {
-                output.holder = input.method;
+                output.holder = input.element;
                 output.holderTag = tags[i];
                 output.inlineTags = input.isFirstSentence ?
                     tags[i].firstSentenceTags() : tags[i].inlineTags();
--- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ReturnTaglet.java	Fri May 03 15:08:47 2013 -0700
+++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ReturnTaglet.java	Fri May 03 17:44:38 2013 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 2013, 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
@@ -50,9 +50,9 @@
      * {@inheritDoc}
      */
     public void inherit(DocFinder.Input input, DocFinder.Output output) {
-       Tag[] tags = input.method.tags("return");
+       Tag[] tags = input.element.tags("return");
         if (tags.length > 0) {
-            output.holder = input.method;
+            output.holder = input.element;
             output.holderTag = tags[0];
             output.inlineTags = input.isFirstSentence ?
                 tags[0].firstSentenceTags() : tags[0].inlineTags();
--- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/SeeTaglet.java	Fri May 03 15:08:47 2013 -0700
+++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/SeeTaglet.java	Fri May 03 17:44:38 2013 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 2013, 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
@@ -49,9 +49,9 @@
      * {@inheritDoc}
      */
     public void inherit(DocFinder.Input input, DocFinder.Output output) {
-        Tag[] tags = input.method.seeTags();
+        Tag[] tags = input.element.seeTags();
         if (tags.length > 0) {
-            output.holder = input.method;
+            output.holder = input.element;
             output.holderTag = tags[0];
             output.inlineTags = input.isFirstSentence ?
                 tags[0].firstSentenceTags() : tags[0].inlineTags();
--- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/SimpleTaglet.java	Fri May 03 15:08:47 2013 -0700
+++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/SimpleTaglet.java	Fri May 03 17:44:38 2013 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 2013, 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
@@ -26,6 +26,7 @@
 package com.sun.tools.doclets.internal.toolkit.taglets;
 
 import com.sun.javadoc.*;
+import com.sun.tools.doclets.internal.toolkit.util.DocFinder;
 
 /**
  * A simple single argument custom tag.
@@ -38,7 +39,7 @@
  * @author Jamie Ho
  */
 
-public class SimpleTaglet extends BaseTaglet {
+public class SimpleTaglet extends BaseTaglet implements InheritableTaglet {
 
     /**
      * The marker in the location string for excluded tags.
@@ -199,6 +200,17 @@
         return false;
     }
 
+    @Override
+    public void inherit(DocFinder.Input input, DocFinder.Output output) {
+        Tag[] tags = input.element.tags(tagName);
+        if (tags.length > 0) {
+            output.holder = input.element;
+            output.holderTag = tags[0];
+            output.inlineTags = input.isFirstSentence
+                    ? tags[0].firstSentenceTags() : tags[0].inlineTags();
+        }
+    }
+
     /**
      * {@inheritDoc}
      */
--- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ThrowsTaglet.java	Fri May 03 15:08:47 2013 -0700
+++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ThrowsTaglet.java	Fri May 03 17:44:38 2013 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 2013, 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
@@ -60,15 +60,15 @@
                 throwsTag.exceptionName() :
                 throwsTag.exception().qualifiedName();
         } else {
-            exception = input.method.containingClass().findClass(input.tagId);
+            exception = input.element.containingClass().findClass(input.tagId);
         }
 
-        ThrowsTag[] tags = input.method.throwsTags();
+        ThrowsTag[] tags = ((MethodDoc)input.element).throwsTags();
         for (int i = 0; i < tags.length; i++) {
             if (input.tagId.equals(tags[i].exceptionName()) ||
                 (tags[i].exception() != null &&
                     (input.tagId.equals(tags[i].exception().qualifiedName())))) {
-                output.holder = input.method;
+                output.holder = input.element;
                 output.holderTag = tags[i];
                 output.inlineTags = input.isFirstSentence ?
                     tags[i].firstSentenceTags() : tags[i].inlineTags();
--- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/DocFinder.java	Fri May 03 15:08:47 2013 -0700
+++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/DocFinder.java	Fri May 03 17:44:38 2013 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2013, 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
@@ -48,9 +48,9 @@
      */
     public static class Input {
         /**
-         * The method to search documentation from.
+         * The element to search documentation from.
          */
-        public MethodDoc method = null;
+        public ProgramElementDoc element;
         /**
          * The taglet to search for documentation on behalf of. Null if we want
          * to search for overall documentation.
@@ -84,54 +84,55 @@
          */
         public boolean isTypeVariableParamTag = false;
 
-        public Input() {}
-
-        public Input(MethodDoc method, InheritableTaglet taglet, Tag tag,
+        public Input(ProgramElementDoc element, InheritableTaglet taglet, Tag tag,
                 boolean isFirstSentence, boolean isInheritDocTag) {
-            this.method = method;
+            this(element);
             this.taglet = taglet;
             this.tag = tag;
             this.isFirstSentence = isFirstSentence;
             this.isInheritDocTag = isInheritDocTag;
         }
 
-        public Input(MethodDoc method, InheritableTaglet taglet, String tagId) {
-            this.method = method;
+        public Input(ProgramElementDoc element, InheritableTaglet taglet, String tagId) {
+            this(element);
             this.taglet = taglet;
             this.tagId = tagId;
         }
 
-        public Input(MethodDoc method, InheritableTaglet taglet, String tagId,
+        public Input(ProgramElementDoc element, InheritableTaglet taglet, String tagId,
             boolean isTypeVariableParamTag) {
-            this.method = method;
+            this(element);
             this.taglet = taglet;
             this.tagId = tagId;
             this.isTypeVariableParamTag = isTypeVariableParamTag;
         }
 
-        public Input(MethodDoc method, InheritableTaglet taglet) {
-            this.method = method;
+        public Input(ProgramElementDoc element, InheritableTaglet taglet) {
+            this(element);
             this.taglet = taglet;
         }
 
-        public Input(MethodDoc method) {
-            this.method = method;
+        public Input(ProgramElementDoc element) {
+            if (element == null)
+                throw new NullPointerException();
+            this.element = element;
         }
 
-        public Input(MethodDoc method, boolean isFirstSentence) {
-            this.method = method;
+        public Input(ProgramElementDoc element, boolean isFirstSentence) {
+            this(element);
             this.isFirstSentence = isFirstSentence;
         }
 
         public Input copy() {
-            Input clone = new Input();
-            clone.method = this.method;
+            Input clone = new Input(this.element);
             clone.taglet = this.taglet;
             clone.tagId = this.tagId;
             clone.tag = this.tag;
             clone.isFirstSentence = this.isFirstSentence;
             clone.isInheritDocTag = this.isInheritDocTag;
             clone.isTypeVariableParamTag = this.isTypeVariableParamTag;
+            if (clone.element == null)
+                throw new NullPointerException();
             return clone;
 
         }
@@ -164,8 +165,8 @@
 
         /**
          * When automatically inheriting throws tags, you sometime must inherit
-         * more than one tag.  For example if the method declares that it throws
-         * IOException and the overidden method has throws tags for IOException and
+         * more than one tag.  For example if the element declares that it throws
+         * IOException and the overridden element has throws tags for IOException and
          * ZipException, both tags would be inherited because ZipException is a
          * subclass of IOException.  This subclass of DocFinder.Output allows
          * multiple tag inheritence.
@@ -174,9 +175,9 @@
     }
 
     /**
-     * Search for the requested comments in the given method.  If it does not
-     * have comments, return documentation from the overriden method if possible.
-     * If the overriden method does not exist or does not have documentation to
+     * Search for the requested comments in the given element.  If it does not
+     * have comments, return documentation from the overriden element if possible.
+     * If the overriden element does not exist or does not have documentation to
      * inherit, search for documentation to inherit from implemented methods.
      *
      * @param input the input object used to perform the search.
@@ -186,14 +187,14 @@
     public static Output search(Input input) {
         Output output = new Output();
         if (input.isInheritDocTag) {
-            //Do nothing because "method" does not have any documentation.
+            //Do nothing because "element" does not have any documentation.
             //All it has it {@inheritDoc}.
         } else if (input.taglet == null) {
             //We want overall documentation.
             output.inlineTags = input.isFirstSentence ?
-                input.method.firstSentenceTags() :
-                input.method.inlineTags();
-            output.holder = input.method;
+                input.element.firstSentenceTags() :
+                input.element.inlineTags();
+            output.holder = input.element;
         } else {
             input.taglet.inherit(input, output);
         }
@@ -204,25 +205,38 @@
         output.isValidInheritDocTag = false;
         Input inheritedSearchInput = input.copy();
         inheritedSearchInput.isInheritDocTag = false;
-        if (input.method.overriddenMethod() != null) {
-            inheritedSearchInput.method = input.method.overriddenMethod();
-            output = search(inheritedSearchInput);
-            output.isValidInheritDocTag = true;
-            if (output != null && output.inlineTags.length > 0) {
-                return output;
+        if (input.element instanceof MethodDoc) {
+            MethodDoc overriddenMethod = ((MethodDoc) input.element).overriddenMethod();
+            if (overriddenMethod != null) {
+                inheritedSearchInput.element = overriddenMethod;
+                output = search(inheritedSearchInput);
+                output.isValidInheritDocTag = true;
+                if (output.inlineTags.length > 0) {
+                    return output;
+                }
             }
-        }
-        //NOTE:  When we fix the bug where ClassDoc.interfaceTypes() does
-        //       not pass all implemented interfaces, we will use the
-        //       appropriate method here.
-        MethodDoc[] implementedMethods =
-            (new ImplementedMethods(input.method, null)).build(false);
-        for (int i = 0; i < implementedMethods.length; i++) {
-            inheritedSearchInput.method = implementedMethods[i];
-            output = search(inheritedSearchInput);
-            output.isValidInheritDocTag = true;
-            if (output != null && output.inlineTags.length > 0) {
-                return output;
+            //NOTE:  When we fix the bug where ClassDoc.interfaceTypes() does
+            //       not pass all implemented interfaces, we will use the
+            //       appropriate element here.
+            MethodDoc[] implementedMethods =
+                (new ImplementedMethods((MethodDoc) input.element, null)).build(false);
+            for (int i = 0; i < implementedMethods.length; i++) {
+                inheritedSearchInput.element = implementedMethods[i];
+                output = search(inheritedSearchInput);
+                output.isValidInheritDocTag = true;
+                if (output.inlineTags.length > 0) {
+                    return output;
+                }
+            }
+        } else if (input.element instanceof ClassDoc) {
+            ProgramElementDoc superclass = ((ClassDoc) input.element).superclass();
+            if (superclass != null) {
+                inheritedSearchInput.element = superclass;
+                output = search(inheritedSearchInput);
+                output.isValidInheritDocTag = true;
+                if (output.inlineTags.length > 0) {
+                    return output;
+                }
             }
         }
         return output;
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/test/com/sun/javadoc/InheritDocForUserTags/DocTest.java	Fri May 03 17:44:38 2013 -0700
@@ -0,0 +1,261 @@
+/*
+ * Copyright (c) 2013, 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 8008768
+ * @summary Using {@inheritDoc} in simple tag defined via -tag fails
+ * @author Mike Duigou
+ * @run main DocTest
+ */
+
+import java.io.*;
+
+/**
+ * DocTest documentation.
+ *
+ * @apiNote DocTest API note.
+ * @implSpec DocTest implementation spec.
+ * @implNote DocTest implementation note.
+ */
+public class DocTest {
+    public static void main(String... args) throws Exception {
+        String[] javadoc_args = {
+            "-verbose",
+            "-d", "DocTest",
+            "-tag", "apiNote:optcm:<em>API Note</em>",
+            "-tag", "implSpec:optcm:<em>Implementation Requirements</em>:",
+            "-tag", "implNote:optcm:<em>Implementation Note</em>:",
+            "-package",
+            new File(System.getProperty("test.src"), "DocTest.java").getPath()
+        };
+
+        // javadoc does not report an exit code for an internal exception (!)
+        // so monitor stderr for stack dumps.
+        PrintStream prevErr = System.err;
+        ByteArrayOutputStream err_baos = new ByteArrayOutputStream();
+        PrintStream err_ps = new PrintStream(err_baos);
+        System.setErr(err_ps);
+
+        int rc;
+        try {
+            rc = com.sun.tools.javadoc.Main.execute(javadoc_args);
+        } finally {
+            err_ps.close();
+            System.setErr(prevErr);
+        }
+
+        String err = err_baos.toString();
+        System.err.println(err);
+
+        if (rc != 0)
+            throw new Exception("javadoc exited with rc=" + rc);
+
+        if (err.contains("at com.sun."))
+            throw new Exception("javadoc output contains stack trace");
+    }
+
+    /**
+     * DocTest() documentation.
+     *
+     * @apiNote DocTest() API note.
+     * @implSpec DocTest() implementation spec.
+     * @implNote DocTest() implementation note.
+     */
+    public DocTest() {
+    }
+
+    /**
+     * DocTest.testMethod() documentation.
+     *
+     * @apiNote DocTest.testMethod() API note.
+     * @implSpec DocTest.testMethod() implementation spec.
+     * @implNote DocTest.testMethod() implementation note.
+     */
+    public void testMethod() {
+    }
+}
+
+/**
+ * DocTestWithTags documentation.
+ *
+ * @apiNote DocTestWithTags API note.
+ * <pre>
+ *    DocTestWithTags API note code sample.
+ * </pre>
+ * @implSpec DocTestWithTags implementation spec.
+ * <pre>
+ *    DocTestWithTags implementation spec code sample.
+ * </pre>
+ * @implNote DocTestWithTags implementation note.
+ * <pre>
+ *    DocTestWithTags implementation note code sample.
+ * </pre>
+ */
+class DocTestWithTags {
+
+    /**
+     * DocTestWithTags() documentation.
+     *
+     * @apiNote DocTestWithTags() API note.
+     * <pre>
+     *    DocTestWithTags() API note code sample.
+     * </pre>
+     * @implSpec DocTestWithTags() implementation spec.
+     * <pre>
+     *    DocTestWithTags() implementation spec code sample.
+     * </pre>
+     * @implNote DocTest() implementation note.
+     * <pre>
+     *    DocTest() implementation note code sample.
+     * </pre>
+     */
+    public DocTestWithTags() {
+    }
+
+    /**
+     * DocTest.testMethod() documentation.
+     *
+     * @apiNote DocTestWithTags.testMethod() API note.
+     * <pre>
+     *    DocTestWithTags.testMethod() API note code sample.
+     * </pre>
+     * @implSpec DocTestWithTags.testMethod() implementation spec.
+     * <pre>
+     *    DocTestWithTags.testMethod() API implementation spec code sample.
+     * </pre>
+     * @implNote DocTest.testMethod() implementation note.
+     * <pre>
+     *    DocTest.testMethod() API implementation code sample.
+     * </pre>
+     */
+    public void testMethod() {
+    }
+}
+
+class MinimallyExtendsDocTest extends DocTest {
+}
+
+/**
+ * SimpleExtendsDocTest documentation.
+ */
+class SimpleExtendsDocTest extends DocTest {
+
+    /**
+     * SimpleExtendsDocTest() documentation.
+     */
+    public SimpleExtendsDocTest() {
+
+    }
+
+    /**
+     * SimpleExtendsDocTest.testMethod() documenation.
+     */
+    @java.lang.Override
+    public void testMethod() {
+    }
+}
+
+/**
+ * {@inheritDoc}
+ */
+class SimpleInheritDocDocTest extends DocTest {
+
+    /**
+     * {@inheritDoc}
+     */
+    public SimpleInheritDocDocTest() {
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @java.lang.Override
+    public void testMethod() {
+    }
+}
+
+/**
+ * {@inheritDoc}
+ *
+ * @apiNote {@inheritDoc}
+ * @implSpec {@inheritDoc}
+ * @implNote {@inheritDoc}
+ */
+class FullInheritDocDocTest extends DocTest {
+
+    /**
+     * {@inheritDoc}
+     *
+     * @apiNote {@inheritDoc}
+     * @implSpec {@inheritDoc}
+     * @implNote {@inheritDoc}
+     */
+    public FullInheritDocDocTest() {
+
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @apiNote {@inheritDoc}
+     * @implSpec {@inheritDoc}
+     * @implNote {@inheritDoc}
+     */
+    @java.lang.Override
+    public void testMethod() {
+    }
+}
+
+/**
+ * {@inheritDoc} and FullInheritDocPlusDocTest documentation.
+ *
+ * @implSpec {@inheritDoc} and FullInheritDocPlusDocTest API note.
+ * @implNote {@inheritDoc} and FullInheritDocPlusDocTest implementation specification.
+ * @apiNote {@inheritDoc} and FullInheritDocPlusDocTest implementation note.
+ */
+class FullInheritDocPlusDocTest extends DocTest {
+
+    /**
+     * {@inheritDoc} and FullInheritDocPlusDocTest() documentation.
+     *
+     * @implSpec {@inheritDoc} and FullInheritDocPlusDocTest() API note.
+     * @implNote {@inheritDoc} and FullInheritDocPlusDocTest() implementation specification.
+     * @apiNote {@inheritDoc} and FullInheritDocPlusDocTest() implementation note.
+     */
+    public FullInheritDocPlusDocTest() {
+
+    }
+
+    /**
+     * {@inheritDoc} and FullInheritDocPlusDocTest.testMethod() documentation.
+     *
+     * @implSpec {@inheritDoc} and FullInheritDocPlusDocTest.testMethod() API note.
+     * @implNote {@inheritDoc} and FullInheritDocPlusDocTest.testMethod() implementation specification.
+     * @apiNote {@inheritDoc} and FullInheritDocPlusDocTest.testMethod() implementation note.
+     */
+    @java.lang.Override
+    public void testMethod() {
+    }
+}
+
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/test/com/sun/javadoc/testSimpleTagInherit/TestSimpleTagInherit.java	Fri May 03 17:44:38 2013 -0700
@@ -0,0 +1,80 @@
+/*
+ * Copyright (c) 2013, 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      8008768
+ * @summary  Using {@inheritDoc} in simple tag defined via -tag fails
+ * @library  ../lib/
+ * @build    JavadocTester TestSimpleTagInherit
+ * @run main TestSimpleTagInherit
+ */
+
+public class TestSimpleTagInherit extends JavadocTester {
+
+    //Test information.
+    private static final String BUG_ID = "8008768";
+    private static final String OUTPUT_DIR = BUG_ID;
+
+    //Javadoc arguments.
+    private static final String[] ARGS = new String[] {
+        "-d", OUTPUT_DIR, "-sourcepath", SRC_DIR,
+        "-tag", "custom:optcm:<em>Custom:</em>",
+        "p"
+    };
+
+    //Input for string search tests.
+    private static final String[][] TEST = {
+        { BUG_ID + FS + "p" + FS + "TestClass.html",
+          "<dt><span class=\"strong\"><em>Custom:</em></span></dt>" + NL +
+          "  <dd>doc for BaseClass class</dd>" },
+        { BUG_ID + FS + "p" + FS + "TestClass.html",
+          "<dt><span class=\"strong\"><em>Custom:</em></span></dt>" + NL +
+          "  <dd>doc for BaseClass method</dd>" }
+    };
+    private static final String[][] NEGATED_TEST = NO_TEST;
+
+    /**
+     * The entry point of the test.
+     * @param args the array of command line arguments.
+     */
+    public static void main(String[] args) {
+        TestSimpleTagInherit tester = new TestSimpleTagInherit();
+        run(tester, ARGS, TEST, NEGATED_TEST);
+        tester.printSummary();
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public String getBugId() {
+        return BUG_ID;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public String getBugName() {
+        return getClass().getName();
+    }
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/test/com/sun/javadoc/testSimpleTagInherit/p/BaseClass.java	Fri May 03 17:44:38 2013 -0700
@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2013, 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 p;
+
+/**
+ * @custom doc for BaseClass class
+ */
+public class BaseClass {
+    /**
+     * @custom doc for BaseClass method
+     */
+    public void m() { }
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/test/com/sun/javadoc/testSimpleTagInherit/p/TestClass.java	Fri May 03 17:44:38 2013 -0700
@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2013, 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 p;
+
+/**
+ * @custom {@inheritDoc}
+ */
+public class TestClass extends BaseClass {
+    /**
+     * @custom {@inheritDoc}
+     */
+    public void m() { }
+}