From 0f333397297313bada51d56e7a0ccd51415ff364 Mon Sep 17 00:00:00 2001 From: jjg <unknown> Date: Fri, 3 May 2013 17:44:38 -0700 Subject: [PATCH] 8008768: Using {@inheritDoc} in simple tag defined via -tag fails Reviewed-by: jjg, mduigou Contributed-by: jonathan.gibbons@oracle.com, mike.duigou@oracle.com --- .../formats/html/HtmlDocletWriter.java | 19 +- .../toolkit/taglets/InheritDocTaglet.java | 67 +++-- .../internal/toolkit/taglets/ParamTaglet.java | 10 +- .../toolkit/taglets/ReturnTaglet.java | 6 +- .../internal/toolkit/taglets/SeeTaglet.java | 6 +- .../toolkit/taglets/SimpleTaglet.java | 16 +- .../toolkit/taglets/ThrowsTaglet.java | 8 +- .../internal/toolkit/util/DocFinder.java | 106 ++++--- .../InheritDocForUserTags/DocTest.java | 261 ++++++++++++++++++ .../TestSimpleTagInherit.java | 80 ++++++ .../testSimpleTagInherit/p/BaseClass.java | 34 +++ .../testSimpleTagInherit/p/TestClass.java | 34 +++ 12 files changed, 554 insertions(+), 93 deletions(-) create mode 100644 test/com/sun/javadoc/InheritDocForUserTags/DocTest.java create mode 100644 test/com/sun/javadoc/testSimpleTagInherit/TestSimpleTagInherit.java create mode 100644 test/com/sun/javadoc/testSimpleTagInherit/p/BaseClass.java create mode 100644 test/com/sun/javadoc/testSimpleTagInherit/p/TestClass.java diff --git a/src/share/classes/com/sun/tools/doclets/formats/html/HtmlDocletWriter.java b/src/share/classes/com/sun/tools/doclets/formats/html/HtmlDocletWriter.java index d30e8044..a22feeeb 100644 --- a/src/share/classes/com/sun/tools/doclets/formats/html/HtmlDocletWriter.java +++ b/src/share/classes/com/sun/tools/doclets/formats/html/HtmlDocletWriter.java @@ -1497,7 +1497,7 @@ public class HtmlDocletWriter extends HtmlDocWriter { * @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 @@ public class HtmlDocletWriter extends HtmlDocWriter { */ 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); diff --git a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/InheritDocTaglet.java b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/InheritDocTaglet.java index 65924bba..01fb04a6 100644 --- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/InheritDocTaglet.java +++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/InheritDocTaglet.java @@ -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 @@ public class InheritDocTaglet extends BaseInlineTaglet { /** * 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 @@ public class InheritDocTaglet extends BaseInlineTaglet { /** * 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 @@ public class InheritDocTaglet extends BaseInlineTaglet { /** * 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 @@ public class InheritDocTaglet extends BaseInlineTaglet { /** * 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 @@ public class InheritDocTaglet extends BaseInlineTaglet { * 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 @@ public class InheritDocTaglet extends BaseInlineTaglet { 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 @@ public class InheritDocTaglet extends BaseInlineTaglet { * @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); } } diff --git a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ParamTaglet.java b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ParamTaglet.java index ad4bf8be..1776411e 100644 --- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ParamTaglet.java +++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ParamTaglet.java @@ -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 @@ public class ParamTaglet extends BaseTaglet implements InheritableTaglet { } } 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(); diff --git a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ReturnTaglet.java b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ReturnTaglet.java index 9d98a969..01212c25 100644 --- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ReturnTaglet.java +++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ReturnTaglet.java @@ -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 @@ public class ReturnTaglet extends BaseExecutableMemberTaglet * {@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(); diff --git a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/SeeTaglet.java b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/SeeTaglet.java index 4e3e8107..1b32eef3 100644 --- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/SeeTaglet.java +++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/SeeTaglet.java @@ -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 @@ public class SeeTaglet extends BaseTaglet implements InheritableTaglet { * {@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(); diff --git a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/SimpleTaglet.java b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/SimpleTaglet.java index 4b21cbd4..0a40b0c4 100644 --- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/SimpleTaglet.java +++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/SimpleTaglet.java @@ -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 @@ import com.sun.javadoc.*; * @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 @@ public class SimpleTaglet extends BaseTaglet { 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} */ diff --git a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ThrowsTaglet.java b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ThrowsTaglet.java index 7b8b365b..fb04ef58 100644 --- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ThrowsTaglet.java +++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ThrowsTaglet.java @@ -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 @@ public class ThrowsTaglet extends BaseExecutableMemberTaglet 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(); diff --git a/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/DocFinder.java b/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/DocFinder.java index a0e4015d..d68b09d1 100644 --- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/DocFinder.java +++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/DocFinder.java @@ -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 class DocFinder { */ 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 class DocFinder { */ 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 @@ public class DocFinder { /** * 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 @@ public class DocFinder { } /** - * 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 class DocFinder { 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 @@ public class DocFinder { 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; diff --git a/test/com/sun/javadoc/InheritDocForUserTags/DocTest.java b/test/com/sun/javadoc/InheritDocForUserTags/DocTest.java new file mode 100644 index 00000000..04d77e35 --- /dev/null +++ b/test/com/sun/javadoc/InheritDocForUserTags/DocTest.java @@ -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() { + } +} + diff --git a/test/com/sun/javadoc/testSimpleTagInherit/TestSimpleTagInherit.java b/test/com/sun/javadoc/testSimpleTagInherit/TestSimpleTagInherit.java new file mode 100644 index 00000000..0b2ac660 --- /dev/null +++ b/test/com/sun/javadoc/testSimpleTagInherit/TestSimpleTagInherit.java @@ -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(); + } +} diff --git a/test/com/sun/javadoc/testSimpleTagInherit/p/BaseClass.java b/test/com/sun/javadoc/testSimpleTagInherit/p/BaseClass.java new file mode 100644 index 00000000..c7a6e177 --- /dev/null +++ b/test/com/sun/javadoc/testSimpleTagInherit/p/BaseClass.java @@ -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() { } +} diff --git a/test/com/sun/javadoc/testSimpleTagInherit/p/TestClass.java b/test/com/sun/javadoc/testSimpleTagInherit/p/TestClass.java new file mode 100644 index 00000000..80c10010 --- /dev/null +++ b/test/com/sun/javadoc/testSimpleTagInherit/p/TestClass.java @@ -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() { } +} -- GitLab