8157682: @inheritDoc doesn't work with @exception

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

8157682: @inheritDoc doesn't work with @exception

Yano, Masanori
Hello.

TagletManager registers a SimpleTaglet for handling @exception tags.
But because inherit() method of SimpleTaglet handles only the first encountered tag,
two or more @exception tags cannot be handled by this way.
In addition, this method cannot inherit description from @throws tags of super class.

I propose to create a new ExceptionTaglet specific for handling @exception tags
rather than use SimpleTaglet.

Please review the following changes.

diff -r 046533575954 -r 34fe25800df3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ExceptionTaglet.java
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ExceptionTaglet.java   Wed Sep 25 16:21:24 2019 +0900
@@ -0,0 +1,69 @@
+package jdk.javadoc.internal.doclets.toolkit.taglets;
+
+import java.util.EnumSet;
+import java.util.List;
+import java.util.Set;
+
+import javax.lang.model.element.Element;
+import javax.lang.model.element.TypeElement;
+
+import com.sun.source.doctree.DocTree;
+
+import jdk.javadoc.internal.doclets.toolkit.Content;
+import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
+import jdk.javadoc.internal.doclets.toolkit.util.DocFinder;
+import jdk.javadoc.internal.doclets.toolkit.util.DocFinder.Input;
+import jdk.javadoc.internal.doclets.toolkit.util.Utils;
+
+import static com.sun.source.doctree.DocTree.Kind.EXCEPTION;
+
+/**
+ * A taglet that represents the @exception 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 ExceptionTaglet extends SimpleTaglet {
+
+    /**
+     * Construct a <code>ExceptionTaglet</code>.
+     */
+    public ExceptionTaglet() {
+        super(EXCEPTION.tagName, null, EnumSet.of(Site.CONSTRUCTOR, Site.METHOD), true);
+    }
+
+    @Override
+    public void inherit(DocFinder.Input input, DocFinder.Output output) {
+        Utils utils = input.utils;
+        Element exception;
+        CommentHelper ch = utils.getCommentHelper(input.element);
+        if (input.tagId == null) {
+            exception = ch.getException(utils.configuration, input.docTreeInfo.docTree);
+            input.tagId = exception == null
+                    ? ch.getExceptionName(input.docTreeInfo.docTree).getSignature()
+                    : utils.getFullyQualifiedName(exception);
+        } else {
+            TypeElement element = input.utils.findClass(input.element, input.tagId);
+            exception = (element == null) ? null : element;
+        }
+
+        for (DocTree dt : input.utils.getThrowsTrees(input.element)) {
+            Element texception = ch.getException(utils.configuration, dt);
+            if (texception != null && (input.tagId.equals(utils.getSimpleName(texception)) ||
+                 (input.tagId.equals(utils.getFullyQualifiedName(texception))))) {
+                output.holder = input.element;
+                output.holderTag = dt;
+                output.inlineTags = ch.getBody(input.utils.configuration, output.holderTag);
+                output.tagList.add(dt);
+            } else if (exception != null && texception != null &&
+                    utils.isTypeElement(texception) && utils.isTypeElement(exception) &&
+                    utils.isSubclassOf((TypeElement)texception, (TypeElement)exception)) {
+                output.tagList.add(dt);
+            }
+        }
+    }
+}
+
diff -r 046533575954 -r 34fe25800df3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java     Sat Jan 26 15:47:50 2019 +0900
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java     Wed Sep 25 16:21:24 2019 +0900
@@ -608,9 +608,7 @@
         addStandardTaglet(new ParamTaglet());
         addStandardTaglet(new ReturnTaglet());
         addStandardTaglet(new ThrowsTaglet());
-        addStandardTaglet(
-                new SimpleTaglet(EXCEPTION.tagName, null,
-                    EnumSet.of(Site.METHOD, Site.CONSTRUCTOR)));
+        addStandardTaglet(new ExceptionTaglet());
         addStandardTaglet(
                 new SimpleTaglet(SINCE.tagName, resources.getText("doclet.Since"),
                     EnumSet.allOf(Site.class), !nosince));
diff -r f54e328f0c60 -r 66621f0835f2 test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A.java
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A.java Tue Sep 24 15:29:17 2019 +0900
@@ -0,0 +1,8 @@
+public class A {
+    /**
+     * @param x a number
+     * @exception NullPointerException if x is null
+     * @exception IllegalArgumentException if {@code x < 0}
+     */
+    public void m(Integer x) { }
+}
diff -r f54e328f0c60 -r 66621f0835f2 test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A_Sub.java
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A_Sub.java     Tue Sep 24 15:29:17 2019 +0900
@@ -0,0 +1,9 @@
+public class A_Sub extends A {
+    /**
+     * @param x {@inheritDoc}
+     * @exception NullPointerException {@inheritDoc}
+     * @exception IllegalArgumentException {@inheritDoc}
+     */
+    @Override
+    public void m(Integer x) { }
+}
diff -r f54e328f0c60 -r 66621f0835f2 test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B.java
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B.java Tue Sep 24 15:29:17 2019 +0900
@@ -0,0 +1,8 @@
+public class B {
+    /**
+     * @param x a number
+     * @throws NullPointerException if x is null
+     * @throws IllegalArgumentException if {@code x < 0}
+     */
+    public void m(Integer x) { }
+}
diff -r f54e328f0c60 -r 66621f0835f2 test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B_Sub.java
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B_Sub.java     Tue Sep 24 15:29:17 2019 +0900
@@ -0,0 +1,9 @@
+public class B_Sub extends B {
+    /**
+     * @param x {@inheritDoc}
+     * @exception NullPointerException {@inheritDoc}
+     * @exception IllegalArgumentException {@inheritDoc}
+     */
+    @Override
+    public void m(Integer x) { }
+}
diff -r f54e328f0c60 -r 66621f0835f2 test/langtools/jdk/javadoc/doclet/testExceptionInheritence/Bug8157682.java
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/Bug8157682.java        Tue Sep 24 15:29:17 2019 +0900
@@ -0,0 +1,43 @@
+/*
+ * @test
+ * @bug 8157682
+ * @summary This test verifies that exception tags can inherit property.
+ * @library ../../lib
+ * @modules jdk.javadoc/jdk.javadoc.internal.tool
+ * @build javadoc.tester.*
+ * @run main Bug8157682
+ */
+
+import javadoc.tester.JavadocTester;
+
+public class Bug8157682 extends JavadocTester {
+
+    public static void main(String... args) throws Exception {
+        Bug8157682 tester = new Bug8157682();
+        tester.runTests();
+    }
+
+    @Test
+    public void test() {
+        javadoc("-d", "out",
+                "-sourcepath", testSrc,
+                testSrc("A.java"),
+                testSrc("B.java"),
+                testSrc("A_Sub.java"),
+                testSrc("B_Sub.java"));
+        checkExit(Exit.OK);
+
+        checkOutput("A_Sub.html", true,
+                "<code>java.lang.NullPointerException</code> - if x is null");
+
+        checkOutput("A_Sub.html", true,
+                "<code>java.lang.IllegalArgumentException</code> - if <code>x &lt; 0</code>");
+
+        checkOutput("B_Sub.html", true,
+                "<code>java.lang.NullPointerException</code> - if x is null");
+
+        checkOutput("B_Sub.html", true,
+                "<code>java.lang.IllegalArgumentException</code> - if <code>x &lt; 0</code>");
+    }
+
+}

Regards,
Masanori Yano
Reply | Threaded
Open this post in threaded view
|

Re: 8157682: @inheritDoc doesn't work with @exception

Jonathan Gibbons
Hi Masanori,

Thank you for your contribution.

I see you are covered by an OCA, but you are not yet an OpenJDK Author,  
is that correct?

I'll sponsor your change, filing an issue, posting a webrev and getting  
a review.

-- Jon

On 9/25/19 6:41 PM, Yano, Masanori wrote:

> Hello.
>
> TagletManager registers a SimpleTaglet for handling @exception tags.
> But because inherit() method of SimpleTaglet handles only the first encountered tag,
> two or more @exception tags cannot be handled by this way.
> In addition, this method cannot inherit description from @throws tags of super class.
>
> I propose to create a new ExceptionTaglet specific for handling @exception tags
> rather than use SimpleTaglet.
>
> Please review the following changes.
>
> diff -r 046533575954 -r 34fe25800df3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ExceptionTaglet.java
> --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ExceptionTaglet.java   Wed Sep 25 16:21:24 2019 +0900
> @@ -0,0 +1,69 @@
> +package jdk.javadoc.internal.doclets.toolkit.taglets;
> +
> +import java.util.EnumSet;
> +import java.util.List;
> +import java.util.Set;
> +
> +import javax.lang.model.element.Element;
> +import javax.lang.model.element.TypeElement;
> +
> +import com.sun.source.doctree.DocTree;
> +
> +import jdk.javadoc.internal.doclets.toolkit.Content;
> +import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
> +import jdk.javadoc.internal.doclets.toolkit.util.DocFinder;
> +import jdk.javadoc.internal.doclets.toolkit.util.DocFinder.Input;
> +import jdk.javadoc.internal.doclets.toolkit.util.Utils;
> +
> +import static com.sun.source.doctree.DocTree.Kind.EXCEPTION;
> +
> +/**
> + * A taglet that represents the @exception 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 ExceptionTaglet extends SimpleTaglet {
> +
> +    /**
> +     * Construct a <code>ExceptionTaglet</code>.
> +     */
> +    public ExceptionTaglet() {
> +        super(EXCEPTION.tagName, null, EnumSet.of(Site.CONSTRUCTOR, Site.METHOD), true);
> +    }
> +
> +    @Override
> +    public void inherit(DocFinder.Input input, DocFinder.Output output) {
> +        Utils utils = input.utils;
> +        Element exception;
> +        CommentHelper ch = utils.getCommentHelper(input.element);
> +        if (input.tagId == null) {
> +            exception = ch.getException(utils.configuration, input.docTreeInfo.docTree);
> +            input.tagId = exception == null
> +                    ? ch.getExceptionName(input.docTreeInfo.docTree).getSignature()
> +                    : utils.getFullyQualifiedName(exception);
> +        } else {
> +            TypeElement element = input.utils.findClass(input.element, input.tagId);
> +            exception = (element == null) ? null : element;
> +        }
> +
> +        for (DocTree dt : input.utils.getThrowsTrees(input.element)) {
> +            Element texception = ch.getException(utils.configuration, dt);
> +            if (texception != null && (input.tagId.equals(utils.getSimpleName(texception)) ||
> +                 (input.tagId.equals(utils.getFullyQualifiedName(texception))))) {
> +                output.holder = input.element;
> +                output.holderTag = dt;
> +                output.inlineTags = ch.getBody(input.utils.configuration, output.holderTag);
> +                output.tagList.add(dt);
> +            } else if (exception != null && texception != null &&
> +                    utils.isTypeElement(texception) && utils.isTypeElement(exception) &&
> +                    utils.isSubclassOf((TypeElement)texception, (TypeElement)exception)) {
> +                output.tagList.add(dt);
> +            }
> +        }
> +    }
> +}
> +
> diff -r 046533575954 -r 34fe25800df3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java
> --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java     Sat Jan 26 15:47:50 2019 +0900
> +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java     Wed Sep 25 16:21:24 2019 +0900
> @@ -608,9 +608,7 @@
>           addStandardTaglet(new ParamTaglet());
>           addStandardTaglet(new ReturnTaglet());
>           addStandardTaglet(new ThrowsTaglet());
> -        addStandardTaglet(
> -                new SimpleTaglet(EXCEPTION.tagName, null,
> -                    EnumSet.of(Site.METHOD, Site.CONSTRUCTOR)));
> +        addStandardTaglet(new ExceptionTaglet());
>           addStandardTaglet(
>                   new SimpleTaglet(SINCE.tagName, resources.getText("doclet.Since"),
>                       EnumSet.allOf(Site.class), !nosince));
> diff -r f54e328f0c60 -r 66621f0835f2 test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A.java
> --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> +++ b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A.java Tue Sep 24 15:29:17 2019 +0900
> @@ -0,0 +1,8 @@
> +public class A {
> +    /**
> +     * @param x a number
> +     * @exception NullPointerException if x is null
> +     * @exception IllegalArgumentException if {@code x < 0}
> +     */
> +    public void m(Integer x) { }
> +}
> diff -r f54e328f0c60 -r 66621f0835f2 test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A_Sub.java
> --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> +++ b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A_Sub.java     Tue Sep 24 15:29:17 2019 +0900
> @@ -0,0 +1,9 @@
> +public class A_Sub extends A {
> +    /**
> +     * @param x {@inheritDoc}
> +     * @exception NullPointerException {@inheritDoc}
> +     * @exception IllegalArgumentException {@inheritDoc}
> +     */
> +    @Override
> +    public void m(Integer x) { }
> +}
> diff -r f54e328f0c60 -r 66621f0835f2 test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B.java
> --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> +++ b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B.java Tue Sep 24 15:29:17 2019 +0900
> @@ -0,0 +1,8 @@
> +public class B {
> +    /**
> +     * @param x a number
> +     * @throws NullPointerException if x is null
> +     * @throws IllegalArgumentException if {@code x < 0}
> +     */
> +    public void m(Integer x) { }
> +}
> diff -r f54e328f0c60 -r 66621f0835f2 test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B_Sub.java
> --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> +++ b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B_Sub.java     Tue Sep 24 15:29:17 2019 +0900
> @@ -0,0 +1,9 @@
> +public class B_Sub extends B {
> +    /**
> +     * @param x {@inheritDoc}
> +     * @exception NullPointerException {@inheritDoc}
> +     * @exception IllegalArgumentException {@inheritDoc}
> +     */
> +    @Override
> +    public void m(Integer x) { }
> +}
> diff -r f54e328f0c60 -r 66621f0835f2 test/langtools/jdk/javadoc/doclet/testExceptionInheritence/Bug8157682.java
> --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> +++ b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/Bug8157682.java        Tue Sep 24 15:29:17 2019 +0900
> @@ -0,0 +1,43 @@
> +/*
> + * @test
> + * @bug 8157682
> + * @summary This test verifies that exception tags can inherit property.
> + * @library ../../lib
> + * @modules jdk.javadoc/jdk.javadoc.internal.tool
> + * @build javadoc.tester.*
> + * @run main Bug8157682
> + */
> +
> +import javadoc.tester.JavadocTester;
> +
> +public class Bug8157682 extends JavadocTester {
> +
> +    public static void main(String... args) throws Exception {
> +        Bug8157682 tester = new Bug8157682();
> +        tester.runTests();
> +    }
> +
> +    @Test
> +    public void test() {
> +        javadoc("-d", "out",
> +                "-sourcepath", testSrc,
> +                testSrc("A.java"),
> +                testSrc("B.java"),
> +                testSrc("A_Sub.java"),
> +                testSrc("B_Sub.java"));
> +        checkExit(Exit.OK);
> +
> +        checkOutput("A_Sub.html", true,
> +                "<code>java.lang.NullPointerException</code> - if x is null");
> +
> +        checkOutput("A_Sub.html", true,
> +                "<code>java.lang.IllegalArgumentException</code> - if <code>x &lt; 0</code>");
> +
> +        checkOutput("B_Sub.html", true,
> +                "<code>java.lang.NullPointerException</code> - if x is null");
> +
> +        checkOutput("B_Sub.html", true,
> +                "<code>java.lang.IllegalArgumentException</code> - if <code>x &lt; 0</code>");
> +    }
> +
> +}
>
> Regards,
> Masanori Yano
Reply | Threaded
Open this post in threaded view
|

RE: 8157682: @inheritDoc doesn't work with @exception

Yano, Masanori
Hi Jon,

Thank you for your reply.

I am not an OpenJDK Author as you said. I am a Contributor.
So, please sponsor my change.

Regards,
Masanori Yano

> -----Original Message-----
> From: Jonathan Gibbons [mailto:[hidden email]]
> Sent: Thursday, September 26, 2019 12:34 PM
> To: Yano, Masanori <[hidden email]>;
> '[hidden email]' <[hidden email]>
> Subject: Re: 8157682: @inheritDoc doesn't work with @exception
>
> Hi Masanori,
>
> Thank you for your contribution.
>
> I see you are covered by an OCA, but you are not yet an OpenJDK Author,
> is that correct?
>
> I'll sponsor your change, filing an issue, posting a webrev and getting
> a review.
>
> -- Jon
>
> On 9/25/19 6:41 PM, Yano, Masanori wrote:
> > Hello.
> >
> > TagletManager registers a SimpleTaglet for handling @exception tags.
> > But because inherit() method of SimpleTaglet handles only the first
> > encountered tag, two or more @exception tags cannot be handled by this
> way.
> > In addition, this method cannot inherit description from @throws tags
> of super class.
> >
> > I propose to create a new ExceptionTaglet specific for handling
> > @exception tags rather than use SimpleTaglet.
> >
> > Please review the following changes.
> >
> > diff -r 046533575954 -r 34fe25800df3
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/tag
> lets/ExceptionTaglet.java
> > --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> > +++
> b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/t
> aglets/ExceptionTaglet.java   Wed Sep 25 16:21:24 2019 +0900
> > @@ -0,0 +1,69 @@
> > +package jdk.javadoc.internal.doclets.toolkit.taglets;
> > +
> > +import java.util.EnumSet;
> > +import java.util.List;
> > +import java.util.Set;
> > +
> > +import javax.lang.model.element.Element; import
> > +javax.lang.model.element.TypeElement;
> > +
> > +import com.sun.source.doctree.DocTree;
> > +
> > +import jdk.javadoc.internal.doclets.toolkit.Content;
> > +import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
> > +import jdk.javadoc.internal.doclets.toolkit.util.DocFinder;
> > +import jdk.javadoc.internal.doclets.toolkit.util.DocFinder.Input;
> > +import jdk.javadoc.internal.doclets.toolkit.util.Utils;
> > +
> > +import static com.sun.source.doctree.DocTree.Kind.EXCEPTION;
> > +
> > +/**
> > + * A taglet that represents the @exception 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 ExceptionTaglet extends SimpleTaglet {
> > +
> > +    /**
> > +     * Construct a <code>ExceptionTaglet</code>.
> > +     */
> > +    public ExceptionTaglet() {
> > +        super(EXCEPTION.tagName, null, EnumSet.of(Site.CONSTRUCTOR,
> Site.METHOD), true);
> > +    }
> > +
> > +    @Override
> > +    public void inherit(DocFinder.Input input, DocFinder.Output
> output) {
> > +        Utils utils = input.utils;
> > +        Element exception;
> > +        CommentHelper ch = utils.getCommentHelper(input.element);
> > +        if (input.tagId == null) {
> > +            exception = ch.getException(utils.configuration,
> input.docTreeInfo.docTree);
> > +            input.tagId = exception == null
> > +                    ?
> ch.getExceptionName(input.docTreeInfo.docTree).getSignature()
> > +                    : utils.getFullyQualifiedName(exception);
> > +        } else {
> > +            TypeElement element = input.utils.findClass(input.element,
> input.tagId);
> > +            exception = (element == null) ? null : element;
> > +        }
> > +
> > +        for (DocTree dt : input.utils.getThrowsTrees(input.element))
> {
> > +            Element texception = ch.getException(utils.configuration,
> dt);
> > +            if (texception != null &&
> (input.tagId.equals(utils.getSimpleName(texception)) ||
> > +
> (input.tagId.equals(utils.getFullyQualifiedName(texception))))) {
> > +                output.holder = input.element;
> > +                output.holderTag = dt;
> > +                output.inlineTags =
> ch.getBody(input.utils.configuration, output.holderTag);
> > +                output.tagList.add(dt);
> > +            } else if (exception != null && texception != null &&
> > +                    utils.isTypeElement(texception) &&
> utils.isTypeElement(exception) &&
> > +                    utils.isSubclassOf((TypeElement)texception,
> (TypeElement)exception)) {
> > +                output.tagList.add(dt);
> > +            }
> > +        }
> > +    }
> > +}
> > +
> > diff -r 046533575954 -r 34fe25800df3
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/tag
> lets/TagletManager.java
> > ---
> a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/t
> aglets/TagletManager.java     Sat Jan 26 15:47:50 2019 +0900
> > +++
> b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/t
> aglets/TagletManager.java     Wed Sep 25 16:21:24 2019 +0900
> > @@ -608,9 +608,7 @@
> >           addStandardTaglet(new ParamTaglet());
> >           addStandardTaglet(new ReturnTaglet());
> >           addStandardTaglet(new ThrowsTaglet());
> > -        addStandardTaglet(
> > -                new SimpleTaglet(EXCEPTION.tagName, null,
> > -                    EnumSet.of(Site.METHOD, Site.CONSTRUCTOR)));
> > +        addStandardTaglet(new ExceptionTaglet());
> >           addStandardTaglet(
> >                   new SimpleTaglet(SINCE.tagName,
> resources.getText("doclet.Since"),
> >                       EnumSet.allOf(Site.class), !nosince)); diff -r
> > f54e328f0c60 -r 66621f0835f2
> test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A.java
> > --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> > +++
> b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A.jav
> > +++ a Tue Sep 24 15:29:17 2019 +0900
> > @@ -0,0 +1,8 @@
> > +public class A {
> > +    /**
> > +     * @param x a number
> > +     * @exception NullPointerException if x is null
> > +     * @exception IllegalArgumentException if {@code x < 0}
> > +     */
> > +    public void m(Integer x) { }
> > +}
> > diff -r f54e328f0c60 -r 66621f0835f2
> test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A_Sub.java
> > --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> > +++
> b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A_Sub.jav
> a     Tue Sep 24 15:29:17 2019 +0900
> > @@ -0,0 +1,9 @@
> > +public class A_Sub extends A {
> > +    /**
> > +     * @param x {@inheritDoc}
> > +     * @exception NullPointerException {@inheritDoc}
> > +     * @exception IllegalArgumentException {@inheritDoc}
> > +     */
> > +    @Override
> > +    public void m(Integer x) { }
> > +}
> > diff -r f54e328f0c60 -r 66621f0835f2
> test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B.java
> > --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> > +++
> b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B.jav
> > +++ a Tue Sep 24 15:29:17 2019 +0900
> > @@ -0,0 +1,8 @@
> > +public class B {
> > +    /**
> > +     * @param x a number
> > +     * @throws NullPointerException if x is null
> > +     * @throws IllegalArgumentException if {@code x < 0}
> > +     */
> > +    public void m(Integer x) { }
> > +}
> > diff -r f54e328f0c60 -r 66621f0835f2
> test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B_Sub.java
> > --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> > +++
> b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B_Sub.jav
> a     Tue Sep 24 15:29:17 2019 +0900
> > @@ -0,0 +1,9 @@
> > +public class B_Sub extends B {
> > +    /**
> > +     * @param x {@inheritDoc}
> > +     * @exception NullPointerException {@inheritDoc}
> > +     * @exception IllegalArgumentException {@inheritDoc}
> > +     */
> > +    @Override
> > +    public void m(Integer x) { }
> > +}
> > diff -r f54e328f0c60 -r 66621f0835f2
> test/langtools/jdk/javadoc/doclet/testExceptionInheritence/Bug8157682.
> java
> > --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> > +++
> b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/Bug815768
> 2.java        Tue Sep 24 15:29:17 2019 +0900
> > @@ -0,0 +1,43 @@
> > +/*
> > + * @test
> > + * @bug 8157682
> > + * @summary This test verifies that exception tags can inherit property.
> > + * @library ../../lib
> > + * @modules jdk.javadoc/jdk.javadoc.internal.tool
> > + * @build javadoc.tester.*
> > + * @run main Bug8157682
> > + */
> > +
> > +import javadoc.tester.JavadocTester;
> > +
> > +public class Bug8157682 extends JavadocTester {
> > +
> > +    public static void main(String... args) throws Exception {
> > +        Bug8157682 tester = new Bug8157682();
> > +        tester.runTests();
> > +    }
> > +
> > +    @Test
> > +    public void test() {
> > +        javadoc("-d", "out",
> > +                "-sourcepath", testSrc,
> > +                testSrc("A.java"),
> > +                testSrc("B.java"),
> > +                testSrc("A_Sub.java"),
> > +                testSrc("B_Sub.java"));
> > +        checkExit(Exit.OK);
> > +
> > +        checkOutput("A_Sub.html", true,
> > +                "<code>java.lang.NullPointerException</code> - if x
> > + is null");
> > +
> > +        checkOutput("A_Sub.html", true,
> > +                "<code>java.lang.IllegalArgumentException</code> - if
> > + <code>x &lt; 0</code>");
> > +
> > +        checkOutput("B_Sub.html", true,
> > +                "<code>java.lang.NullPointerException</code> - if x
> > + is null");
> > +
> > +        checkOutput("B_Sub.html", true,
> > +                "<code>java.lang.IllegalArgumentException</code> - if
> <code>x &lt; 0</code>");
> > +    }
> > +
> > +}
> >
> > Regards,
> > Masanori Yano
Reply | Threaded
Open this post in threaded view
|

RE: 8157682: @inheritDoc doesn't work with @exception

yano-masanori@fujitsu.com
Hi Jon,

It's been a year since I asked for a sponsor, so please tell me
the progress of this bug fixing work.

Regards,
Masanori Yano

> -----Original Message-----
> From: Yano, Masanori
> Sent: Thursday, September 26, 2019 2:28 PM
> To: 'Jonathan Gibbons' <[hidden email]>;
> '[hidden email]' <[hidden email]>
> Subject: RE: 8157682: @inheritDoc doesn't work with @exception
>
> Hi Jon,
>
> Thank you for your reply.
>
> I am not an OpenJDK Author as you said. I am a Contributor.
> So, please sponsor my change.
>
> Regards,
> Masanori Yano
>
> > -----Original Message-----
> > From: Jonathan Gibbons [mailto:[hidden email]]
> > Sent: Thursday, September 26, 2019 12:34 PM
> > To: Yano, Masanori <[hidden email]>;
> > '[hidden email]' <[hidden email]>
> > Subject: Re: 8157682: @inheritDoc doesn't work with @exception
> >
> > Hi Masanori,
> >
> > Thank you for your contribution.
> >
> > I see you are covered by an OCA, but you are not yet an OpenJDK
> > Author, is that correct?
> >
> > I'll sponsor your change, filing an issue, posting a webrev and
> > getting a review.
> >
> > -- Jon
> >
> > On 9/25/19 6:41 PM, Yano, Masanori wrote:
> > > Hello.
> > >
> > > TagletManager registers a SimpleTaglet for handling @exception tags.
> > > But because inherit() method of SimpleTaglet handles only the first
> > > encountered tag, two or more @exception tags cannot be handled by
> > > this
> > way.
> > > In addition, this method cannot inherit description from @throws
> > > tags
> > of super class.
> > >
> > > I propose to create a new ExceptionTaglet specific for handling
> > > @exception tags rather than use SimpleTaglet.
> > >
> > > Please review the following changes.
> > >
> > > diff -r 046533575954 -r 34fe25800df3
> > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/tag
> > lets/ExceptionTaglet.java
> > > --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> > > +++
> > b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/t
> > aglets/ExceptionTaglet.java   Wed Sep 25 16:21:24 2019 +0900
> > > @@ -0,0 +1,69 @@
> > > +package jdk.javadoc.internal.doclets.toolkit.taglets;
> > > +
> > > +import java.util.EnumSet;
> > > +import java.util.List;
> > > +import java.util.Set;
> > > +
> > > +import javax.lang.model.element.Element; import
> > > +javax.lang.model.element.TypeElement;
> > > +
> > > +import com.sun.source.doctree.DocTree;
> > > +
> > > +import jdk.javadoc.internal.doclets.toolkit.Content;
> > > +import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
> > > +import jdk.javadoc.internal.doclets.toolkit.util.DocFinder;
> > > +import jdk.javadoc.internal.doclets.toolkit.util.DocFinder.Input;
> > > +import jdk.javadoc.internal.doclets.toolkit.util.Utils;
> > > +
> > > +import static com.sun.source.doctree.DocTree.Kind.EXCEPTION;
> > > +
> > > +/**
> > > + * A taglet that represents the @exception 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 ExceptionTaglet extends SimpleTaglet {
> > > +
> > > +    /**
> > > +     * Construct a <code>ExceptionTaglet</code>.
> > > +     */
> > > +    public ExceptionTaglet() {
> > > +        super(EXCEPTION.tagName, null, EnumSet.of(Site.CONSTRUCTOR,
> > Site.METHOD), true);
> > > +    }
> > > +
> > > +    @Override
> > > +    public void inherit(DocFinder.Input input, DocFinder.Output
> > output) {
> > > +        Utils utils = input.utils;
> > > +        Element exception;
> > > +        CommentHelper ch = utils.getCommentHelper(input.element);
> > > +        if (input.tagId == null) {
> > > +            exception = ch.getException(utils.configuration,
> > input.docTreeInfo.docTree);
> > > +            input.tagId = exception == null
> > > +                    ?
> > ch.getExceptionName(input.docTreeInfo.docTree).getSignature()
> > > +                    : utils.getFullyQualifiedName(exception);
> > > +        } else {
> > > +            TypeElement element =
> > > + input.utils.findClass(input.element,
> > input.tagId);
> > > +            exception = (element == null) ? null : element;
> > > +        }
> > > +
> > > +        for (DocTree dt :
> > > + input.utils.getThrowsTrees(input.element))
> > {
> > > +            Element texception =
> > > + ch.getException(utils.configuration,
> > dt);
> > > +            if (texception != null &&
> > (input.tagId.equals(utils.getSimpleName(texception)) ||
> > > +
> > (input.tagId.equals(utils.getFullyQualifiedName(texception))))) {
> > > +                output.holder = input.element;
> > > +                output.holderTag = dt;
> > > +                output.inlineTags =
> > ch.getBody(input.utils.configuration, output.holderTag);
> > > +                output.tagList.add(dt);
> > > +            } else if (exception != null && texception != null &&
> > > +                    utils.isTypeElement(texception) &&
> > utils.isTypeElement(exception) &&
> > > +                    utils.isSubclassOf((TypeElement)texception,
> > (TypeElement)exception)) {
> > > +                output.tagList.add(dt);
> > > +            }
> > > +        }
> > > +    }
> > > +}
> > > +
> > > diff -r 046533575954 -r 34fe25800df3
> > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/tag
> > lets/TagletManager.java
> > > ---
> > a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/t
> > aglets/TagletManager.java     Sat Jan 26 15:47:50 2019 +0900
> > > +++
> > b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/t
> > aglets/TagletManager.java     Wed Sep 25 16:21:24 2019 +0900
> > > @@ -608,9 +608,7 @@
> > >           addStandardTaglet(new ParamTaglet());
> > >           addStandardTaglet(new ReturnTaglet());
> > >           addStandardTaglet(new ThrowsTaglet());
> > > -        addStandardTaglet(
> > > -                new SimpleTaglet(EXCEPTION.tagName, null,
> > > -                    EnumSet.of(Site.METHOD, Site.CONSTRUCTOR)));
> > > +        addStandardTaglet(new ExceptionTaglet());
> > >           addStandardTaglet(
> > >                   new SimpleTaglet(SINCE.tagName,
> > resources.getText("doclet.Since"),
> > >                       EnumSet.allOf(Site.class), !nosince)); diff -r
> > > f54e328f0c60 -r 66621f0835f2
> > test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A.java
> > > --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> > > +++
> > b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A.jav
> > > +++ a Tue Sep 24 15:29:17 2019 +0900
> > > @@ -0,0 +1,8 @@
> > > +public class A {
> > > +    /**
> > > +     * @param x a number
> > > +     * @exception NullPointerException if x is null
> > > +     * @exception IllegalArgumentException if {@code x < 0}
> > > +     */
> > > +    public void m(Integer x) { }
> > > +}
> > > diff -r f54e328f0c60 -r 66621f0835f2
> > test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A_Sub.java
> > > --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> > > +++
> > b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A_Sub.jav
> > a     Tue Sep 24 15:29:17 2019 +0900
> > > @@ -0,0 +1,9 @@
> > > +public class A_Sub extends A {
> > > +    /**
> > > +     * @param x {@inheritDoc}
> > > +     * @exception NullPointerException {@inheritDoc}
> > > +     * @exception IllegalArgumentException {@inheritDoc}
> > > +     */
> > > +    @Override
> > > +    public void m(Integer x) { }
> > > +}
> > > diff -r f54e328f0c60 -r 66621f0835f2
> > test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B.java
> > > --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> > > +++
> > b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B.jav
> > > +++ a Tue Sep 24 15:29:17 2019 +0900
> > > @@ -0,0 +1,8 @@
> > > +public class B {
> > > +    /**
> > > +     * @param x a number
> > > +     * @throws NullPointerException if x is null
> > > +     * @throws IllegalArgumentException if {@code x < 0}
> > > +     */
> > > +    public void m(Integer x) { }
> > > +}
> > > diff -r f54e328f0c60 -r 66621f0835f2
> > test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B_Sub.java
> > > --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> > > +++
> > b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B_Sub.jav
> > a     Tue Sep 24 15:29:17 2019 +0900
> > > @@ -0,0 +1,9 @@
> > > +public class B_Sub extends B {
> > > +    /**
> > > +     * @param x {@inheritDoc}
> > > +     * @exception NullPointerException {@inheritDoc}
> > > +     * @exception IllegalArgumentException {@inheritDoc}
> > > +     */
> > > +    @Override
> > > +    public void m(Integer x) { }
> > > +}
> > > diff -r f54e328f0c60 -r 66621f0835f2
> > test/langtools/jdk/javadoc/doclet/testExceptionInheritence/Bug8157682.
> > java
> > > --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> > > +++
> > b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/Bug815768
> > 2.java        Tue Sep 24 15:29:17 2019 +0900
> > > @@ -0,0 +1,43 @@
> > > +/*
> > > + * @test
> > > + * @bug 8157682
> > > + * @summary This test verifies that exception tags can inherit property.
> > > + * @library ../../lib
> > > + * @modules jdk.javadoc/jdk.javadoc.internal.tool
> > > + * @build javadoc.tester.*
> > > + * @run main Bug8157682
> > > + */
> > > +
> > > +import javadoc.tester.JavadocTester;
> > > +
> > > +public class Bug8157682 extends JavadocTester {
> > > +
> > > +    public static void main(String... args) throws Exception {
> > > +        Bug8157682 tester = new Bug8157682();
> > > +        tester.runTests();
> > > +    }
> > > +
> > > +    @Test
> > > +    public void test() {
> > > +        javadoc("-d", "out",
> > > +                "-sourcepath", testSrc,
> > > +                testSrc("A.java"),
> > > +                testSrc("B.java"),
> > > +                testSrc("A_Sub.java"),
> > > +                testSrc("B_Sub.java"));
> > > +        checkExit(Exit.OK);
> > > +
> > > +        checkOutput("A_Sub.html", true,
> > > +                "<code>java.lang.NullPointerException</code> - if x
> > > + is null");
> > > +
> > > +        checkOutput("A_Sub.html", true,
> > > +                "<code>java.lang.IllegalArgumentException</code> -
> > > + if <code>x &lt; 0</code>");
> > > +
> > > +        checkOutput("B_Sub.html", true,
> > > +                "<code>java.lang.NullPointerException</code> - if x
> > > + is null");
> > > +
> > > +        checkOutput("B_Sub.html", true,
> > > +                "<code>java.lang.IllegalArgumentException</code> -
> > > + if
> > <code>x &lt; 0</code>");
> > > +    }
> > > +
> > > +}
> > >
> > > Regards,
> > > Masanori Yano
Reply | Threaded
Open this post in threaded view
|

RE: 8157682: @inheritDoc doesn't work with @exception

yano-masanori@fujitsu.com
Hi Jon,

This is a ping.
Please tell me the progress of this bug fixing work.

Regards,
Masanori Yano

> -----Original Message-----
> From: Yano, Masanori
> Sent: Thursday, September 24, 2020 11:03 AM
> To: 'Jonathan Gibbons' <[hidden email]>;
> '[hidden email]' <[hidden email]>
> Subject: RE: 8157682: @inheritDoc doesn't work with @exception
>
> Hi Jon,
>
> It's been a year since I asked for a sponsor, so please tell me the progress of this bug
> fixing work.
>
> Regards,
> Masanori Yano
>
> > -----Original Message-----
> > From: Yano, Masanori
> > Sent: Thursday, September 26, 2019 2:28 PM
> > To: 'Jonathan Gibbons' <[hidden email]>;
> > '[hidden email]' <[hidden email]>
> > Subject: RE: 8157682: @inheritDoc doesn't work with @exception
> >
> > Hi Jon,
> >
> > Thank you for your reply.
> >
> > I am not an OpenJDK Author as you said. I am a Contributor.
> > So, please sponsor my change.
> >
> > Regards,
> > Masanori Yano
> >
> > > -----Original Message-----
> > > From: Jonathan Gibbons [mailto:[hidden email]]
> > > Sent: Thursday, September 26, 2019 12:34 PM
> > > To: Yano, Masanori <[hidden email]>;
> > > '[hidden email]' <[hidden email]>
> > > Subject: Re: 8157682: @inheritDoc doesn't work with @exception
> > >
> > > Hi Masanori,
> > >
> > > Thank you for your contribution.
> > >
> > > I see you are covered by an OCA, but you are not yet an OpenJDK
> > > Author, is that correct?
> > >
> > > I'll sponsor your change, filing an issue, posting a webrev and
> > > getting a review.
> > >
> > > -- Jon
> > >
> > > On 9/25/19 6:41 PM, Yano, Masanori wrote:
> > > > Hello.
> > > >
> > > > TagletManager registers a SimpleTaglet for handling @exception tags.
> > > > But because inherit() method of SimpleTaglet handles only the
> > > > first encountered tag, two or more @exception tags cannot be
> > > > handled by this
> > > way.
> > > > In addition, this method cannot inherit description from @throws
> > > > tags
> > > of super class.
> > > >
> > > > I propose to create a new ExceptionTaglet specific for handling
> > > > @exception tags rather than use SimpleTaglet.
> > > >
> > > > Please review the following changes.
> > > >
> > > > diff -r 046533575954 -r 34fe25800df3
> > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/t
> > > ag
> > > lets/ExceptionTaglet.java
> > > > --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> > > > +++
> > > b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/t
> > > aglets/ExceptionTaglet.java   Wed Sep 25 16:21:24 2019 +0900
> > > > @@ -0,0 +1,69 @@
> > > > +package jdk.javadoc.internal.doclets.toolkit.taglets;
> > > > +
> > > > +import java.util.EnumSet;
> > > > +import java.util.List;
> > > > +import java.util.Set;
> > > > +
> > > > +import javax.lang.model.element.Element; import
> > > > +javax.lang.model.element.TypeElement;
> > > > +
> > > > +import com.sun.source.doctree.DocTree;
> > > > +
> > > > +import jdk.javadoc.internal.doclets.toolkit.Content;
> > > > +import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
> > > > +import jdk.javadoc.internal.doclets.toolkit.util.DocFinder;
> > > > +import jdk.javadoc.internal.doclets.toolkit.util.DocFinder.Input;
> > > > +import jdk.javadoc.internal.doclets.toolkit.util.Utils;
> > > > +
> > > > +import static com.sun.source.doctree.DocTree.Kind.EXCEPTION;
> > > > +
> > > > +/**
> > > > + * A taglet that represents the @exception 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 ExceptionTaglet extends SimpleTaglet {
> > > > +
> > > > +    /**
> > > > +     * Construct a <code>ExceptionTaglet</code>.
> > > > +     */
> > > > +    public ExceptionTaglet() {
> > > > +        super(EXCEPTION.tagName, null,
> > > > + EnumSet.of(Site.CONSTRUCTOR,
> > > Site.METHOD), true);
> > > > +    }
> > > > +
> > > > +    @Override
> > > > +    public void inherit(DocFinder.Input input, DocFinder.Output
> > > output) {
> > > > +        Utils utils = input.utils;
> > > > +        Element exception;
> > > > +        CommentHelper ch = utils.getCommentHelper(input.element);
> > > > +        if (input.tagId == null) {
> > > > +            exception = ch.getException(utils.configuration,
> > > input.docTreeInfo.docTree);
> > > > +            input.tagId = exception == null
> > > > +                    ?
> > > ch.getExceptionName(input.docTreeInfo.docTree).getSignature()
> > > > +                    : utils.getFullyQualifiedName(exception);
> > > > +        } else {
> > > > +            TypeElement element =
> > > > + input.utils.findClass(input.element,
> > > input.tagId);
> > > > +            exception = (element == null) ? null : element;
> > > > +        }
> > > > +
> > > > +        for (DocTree dt :
> > > > + input.utils.getThrowsTrees(input.element))
> > > {
> > > > +            Element texception =
> > > > + ch.getException(utils.configuration,
> > > dt);
> > > > +            if (texception != null &&
> > > (input.tagId.equals(utils.getSimpleName(texception)) ||
> > > > +
> > > (input.tagId.equals(utils.getFullyQualifiedName(texception))))) {
> > > > +                output.holder = input.element;
> > > > +                output.holderTag = dt;
> > > > +                output.inlineTags =
> > > ch.getBody(input.utils.configuration, output.holderTag);
> > > > +                output.tagList.add(dt);
> > > > +            } else if (exception != null && texception != null &&
> > > > +                    utils.isTypeElement(texception) &&
> > > utils.isTypeElement(exception) &&
> > > > +                    utils.isSubclassOf((TypeElement)texception,
> > > (TypeElement)exception)) {
> > > > +                output.tagList.add(dt);
> > > > +            }
> > > > +        }
> > > > +    }
> > > > +}
> > > > +
> > > > diff -r 046533575954 -r 34fe25800df3
> > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/t
> > > ag
> > > lets/TagletManager.java
> > > > ---
> > > a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/t
> > > aglets/TagletManager.java     Sat Jan 26 15:47:50 2019 +0900
> > > > +++
> > > b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/t
> > > aglets/TagletManager.java     Wed Sep 25 16:21:24 2019 +0900
> > > > @@ -608,9 +608,7 @@
> > > >           addStandardTaglet(new ParamTaglet());
> > > >           addStandardTaglet(new ReturnTaglet());
> > > >           addStandardTaglet(new ThrowsTaglet());
> > > > -        addStandardTaglet(
> > > > -                new SimpleTaglet(EXCEPTION.tagName, null,
> > > > -                    EnumSet.of(Site.METHOD, Site.CONSTRUCTOR)));
> > > > +        addStandardTaglet(new ExceptionTaglet());
> > > >           addStandardTaglet(
> > > >                   new SimpleTaglet(SINCE.tagName,
> > > resources.getText("doclet.Since"),
> > > >                       EnumSet.allOf(Site.class), !nosince)); diff
> > > > -r
> > > > f54e328f0c60 -r 66621f0835f2
> > > test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A.java
> > > > --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> > > > +++
> > > b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A.jav
> > > > +++ a Tue Sep 24 15:29:17 2019 +0900
> > > > @@ -0,0 +1,8 @@
> > > > +public class A {
> > > > +    /**
> > > > +     * @param x a number
> > > > +     * @exception NullPointerException if x is null
> > > > +     * @exception IllegalArgumentException if {@code x < 0}
> > > > +     */
> > > > +    public void m(Integer x) { }
> > > > +}
> > > > diff -r f54e328f0c60 -r 66621f0835f2
> > > test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A_Sub.jav
> > > a
> > > > --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> > > > +++
> > > b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A_Sub.jav
> > > a     Tue Sep 24 15:29:17 2019 +0900
> > > > @@ -0,0 +1,9 @@
> > > > +public class A_Sub extends A {
> > > > +    /**
> > > > +     * @param x {@inheritDoc}
> > > > +     * @exception NullPointerException {@inheritDoc}
> > > > +     * @exception IllegalArgumentException {@inheritDoc}
> > > > +     */
> > > > +    @Override
> > > > +    public void m(Integer x) { }
> > > > +}
> > > > diff -r f54e328f0c60 -r 66621f0835f2
> > > test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B.java
> > > > --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> > > > +++
> > > b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B.jav
> > > > +++ a Tue Sep 24 15:29:17 2019 +0900
> > > > @@ -0,0 +1,8 @@
> > > > +public class B {
> > > > +    /**
> > > > +     * @param x a number
> > > > +     * @throws NullPointerException if x is null
> > > > +     * @throws IllegalArgumentException if {@code x < 0}
> > > > +     */
> > > > +    public void m(Integer x) { }
> > > > +}
> > > > diff -r f54e328f0c60 -r 66621f0835f2
> > > test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B_Sub.jav
> > > a
> > > > --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> > > > +++
> > > b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B_Sub.jav
> > > a     Tue Sep 24 15:29:17 2019 +0900
> > > > @@ -0,0 +1,9 @@
> > > > +public class B_Sub extends B {
> > > > +    /**
> > > > +     * @param x {@inheritDoc}
> > > > +     * @exception NullPointerException {@inheritDoc}
> > > > +     * @exception IllegalArgumentException {@inheritDoc}
> > > > +     */
> > > > +    @Override
> > > > +    public void m(Integer x) { }
> > > > +}
> > > > diff -r f54e328f0c60 -r 66621f0835f2
> > > test/langtools/jdk/javadoc/doclet/testExceptionInheritence/Bug8157682.
> > > java
> > > > --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> > > > +++
> > > b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/Bug815768
> > > 2.java        Tue Sep 24 15:29:17 2019 +0900
> > > > @@ -0,0 +1,43 @@
> > > > +/*
> > > > + * @test
> > > > + * @bug 8157682
> > > > + * @summary This test verifies that exception tags can inherit property.
> > > > + * @library ../../lib
> > > > + * @modules jdk.javadoc/jdk.javadoc.internal.tool
> > > > + * @build javadoc.tester.*
> > > > + * @run main Bug8157682
> > > > + */
> > > > +
> > > > +import javadoc.tester.JavadocTester;
> > > > +
> > > > +public class Bug8157682 extends JavadocTester {
> > > > +
> > > > +    public static void main(String... args) throws Exception {
> > > > +        Bug8157682 tester = new Bug8157682();
> > > > +        tester.runTests();
> > > > +    }
> > > > +
> > > > +    @Test
> > > > +    public void test() {
> > > > +        javadoc("-d", "out",
> > > > +                "-sourcepath", testSrc,
> > > > +                testSrc("A.java"),
> > > > +                testSrc("B.java"),
> > > > +                testSrc("A_Sub.java"),
> > > > +                testSrc("B_Sub.java"));
> > > > +        checkExit(Exit.OK);
> > > > +
> > > > +        checkOutput("A_Sub.html", true,
> > > > +                "<code>java.lang.NullPointerException</code> - if
> > > > + x is null");
> > > > +
> > > > +        checkOutput("A_Sub.html", true,
> > > > +                "<code>java.lang.IllegalArgumentException</code>
> > > > + - if <code>x &lt; 0</code>");
> > > > +
> > > > +        checkOutput("B_Sub.html", true,
> > > > +                "<code>java.lang.NullPointerException</code> - if
> > > > + x is null");
> > > > +
> > > > +        checkOutput("B_Sub.html", true,
> > > > +                "<code>java.lang.IllegalArgumentException</code>
> > > > + - if
> > > <code>x &lt; 0</code>");
> > > > +    }
> > > > +
> > > > +}
> > > >
> > > > Regards,
> > > > Masanori Yano
Reply | Threaded
Open this post in threaded view
|

Re: 8157682: @inheritDoc doesn't work with @exception

Jonathan Gibbons
In reply to this post by Yano, Masanori
Hi,

I looked in detail at your patch. I understand the problem you're trying  
to solve, but this is not the best way to solve the problem. You're  
introducing a new `ExceptionTaglet` class that provides a subset of the  
functionality of the equivalent `ThrowsTaglet` class. A better way to  
solve the problem is to simply reuse the `ThrowsTaglet` by registering  
it under an additional name.

I looked at your test and rewrote it somewhat to check more combinations  
of `@throws` and `@exception`.

You can see the latest version in this PR on GitHub:  
https://github.com/openjdk/jdk/pull/2818

Thank you for your interest in helping to fix this issue.

-- Jon


On 9/25/19 6:41 PM, Yano, Masanori wrote:

> Hello.
>
> TagletManager registers a SimpleTaglet for handling @exception tags.
> But because inherit() method of SimpleTaglet handles only the first encountered tag,
> two or more @exception tags cannot be handled by this way.
> In addition, this method cannot inherit description from @throws tags of super class.
>
> I propose to create a new ExceptionTaglet specific for handling @exception tags
> rather than use SimpleTaglet.
>
> Please review the following changes.
>
> diff -r 046533575954 -r 34fe25800df3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ExceptionTaglet.java
> --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ExceptionTaglet.java   Wed Sep 25 16:21:24 2019 +0900
> @@ -0,0 +1,69 @@
> +package jdk.javadoc.internal.doclets.toolkit.taglets;
> +
> +import java.util.EnumSet;
> +import java.util.List;
> +import java.util.Set;
> +
> +import javax.lang.model.element.Element;
> +import javax.lang.model.element.TypeElement;
> +
> +import com.sun.source.doctree.DocTree;
> +
> +import jdk.javadoc.internal.doclets.toolkit.Content;
> +import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
> +import jdk.javadoc.internal.doclets.toolkit.util.DocFinder;
> +import jdk.javadoc.internal.doclets.toolkit.util.DocFinder.Input;
> +import jdk.javadoc.internal.doclets.toolkit.util.Utils;
> +
> +import static com.sun.source.doctree.DocTree.Kind.EXCEPTION;
> +
> +/**
> + * A taglet that represents the @exception 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 ExceptionTaglet extends SimpleTaglet {
> +
> +    /**
> +     * Construct a <code>ExceptionTaglet</code>.
> +     */
> +    public ExceptionTaglet() {
> +        super(EXCEPTION.tagName, null, EnumSet.of(Site.CONSTRUCTOR, Site.METHOD), true);
> +    }
> +
> +    @Override
> +    public void inherit(DocFinder.Input input, DocFinder.Output output) {
> +        Utils utils = input.utils;
> +        Element exception;
> +        CommentHelper ch = utils.getCommentHelper(input.element);
> +        if (input.tagId == null) {
> +            exception = ch.getException(utils.configuration, input.docTreeInfo.docTree);
> +            input.tagId = exception == null
> +                    ? ch.getExceptionName(input.docTreeInfo.docTree).getSignature()
> +                    : utils.getFullyQualifiedName(exception);
> +        } else {
> +            TypeElement element = input.utils.findClass(input.element, input.tagId);
> +            exception = (element == null) ? null : element;
> +        }
> +
> +        for (DocTree dt : input.utils.getThrowsTrees(input.element)) {
> +            Element texception = ch.getException(utils.configuration, dt);
> +            if (texception != null && (input.tagId.equals(utils.getSimpleName(texception)) ||
> +                 (input.tagId.equals(utils.getFullyQualifiedName(texception))))) {
> +                output.holder = input.element;
> +                output.holderTag = dt;
> +                output.inlineTags = ch.getBody(input.utils.configuration, output.holderTag);
> +                output.tagList.add(dt);
> +            } else if (exception != null && texception != null &&
> +                    utils.isTypeElement(texception) && utils.isTypeElement(exception) &&
> +                    utils.isSubclassOf((TypeElement)texception, (TypeElement)exception)) {
> +                output.tagList.add(dt);
> +            }
> +        }
> +    }
> +}
> +
> diff -r 046533575954 -r 34fe25800df3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java
> --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java     Sat Jan 26 15:47:50 2019 +0900
> +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java     Wed Sep 25 16:21:24 2019 +0900
> @@ -608,9 +608,7 @@
>           addStandardTaglet(new ParamTaglet());
>           addStandardTaglet(new ReturnTaglet());
>           addStandardTaglet(new ThrowsTaglet());
> -        addStandardTaglet(
> -                new SimpleTaglet(EXCEPTION.tagName, null,
> -                    EnumSet.of(Site.METHOD, Site.CONSTRUCTOR)));
> +        addStandardTaglet(new ExceptionTaglet());
>           addStandardTaglet(
>                   new SimpleTaglet(SINCE.tagName, resources.getText("doclet.Since"),
>                       EnumSet.allOf(Site.class), !nosince));
> diff -r f54e328f0c60 -r 66621f0835f2 test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A.java
> --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> +++ b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A.java Tue Sep 24 15:29:17 2019 +0900
> @@ -0,0 +1,8 @@
> +public class A {
> +    /**
> +     * @param x a number
> +     * @exception NullPointerException if x is null
> +     * @exception IllegalArgumentException if {@code x < 0}
> +     */
> +    public void m(Integer x) { }
> +}
> diff -r f54e328f0c60 -r 66621f0835f2 test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A_Sub.java
> --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> +++ b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/A_Sub.java     Tue Sep 24 15:29:17 2019 +0900
> @@ -0,0 +1,9 @@
> +public class A_Sub extends A {
> +    /**
> +     * @param x {@inheritDoc}
> +     * @exception NullPointerException {@inheritDoc}
> +     * @exception IllegalArgumentException {@inheritDoc}
> +     */
> +    @Override
> +    public void m(Integer x) { }
> +}
> diff -r f54e328f0c60 -r 66621f0835f2 test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B.java
> --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> +++ b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B.java Tue Sep 24 15:29:17 2019 +0900
> @@ -0,0 +1,8 @@
> +public class B {
> +    /**
> +     * @param x a number
> +     * @throws NullPointerException if x is null
> +     * @throws IllegalArgumentException if {@code x < 0}
> +     */
> +    public void m(Integer x) { }
> +}
> diff -r f54e328f0c60 -r 66621f0835f2 test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B_Sub.java
> --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> +++ b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/B_Sub.java     Tue Sep 24 15:29:17 2019 +0900
> @@ -0,0 +1,9 @@
> +public class B_Sub extends B {
> +    /**
> +     * @param x {@inheritDoc}
> +     * @exception NullPointerException {@inheritDoc}
> +     * @exception IllegalArgumentException {@inheritDoc}
> +     */
> +    @Override
> +    public void m(Integer x) { }
> +}
> diff -r f54e328f0c60 -r 66621f0835f2 test/langtools/jdk/javadoc/doclet/testExceptionInheritence/Bug8157682.java
> --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> +++ b/test/langtools/jdk/javadoc/doclet/testExceptionInheritence/Bug8157682.java        Tue Sep 24 15:29:17 2019 +0900
> @@ -0,0 +1,43 @@
> +/*
> + * @test
> + * @bug 8157682
> + * @summary This test verifies that exception tags can inherit property.
> + * @library ../../lib
> + * @modules jdk.javadoc/jdk.javadoc.internal.tool
> + * @build javadoc.tester.*
> + * @run main Bug8157682
> + */
> +
> +import javadoc.tester.JavadocTester;
> +
> +public class Bug8157682 extends JavadocTester {
> +
> +    public static void main(String... args) throws Exception {
> +        Bug8157682 tester = new Bug8157682();
> +        tester.runTests();
> +    }
> +
> +    @Test
> +    public void test() {
> +        javadoc("-d", "out",
> +                "-sourcepath", testSrc,
> +                testSrc("A.java"),
> +                testSrc("B.java"),
> +                testSrc("A_Sub.java"),
> +                testSrc("B_Sub.java"));
> +        checkExit(Exit.OK);
> +
> +        checkOutput("A_Sub.html", true,
> +                "<code>java.lang.NullPointerException</code> - if x is null");
> +
> +        checkOutput("A_Sub.html", true,
> +                "<code>java.lang.IllegalArgumentException</code> - if <code>x &lt; 0</code>");
> +
> +        checkOutput("B_Sub.html", true,
> +                "<code>java.lang.NullPointerException</code> - if x is null");
> +
> +        checkOutput("B_Sub.html", true,
> +                "<code>java.lang.IllegalArgumentException</code> - if <code>x &lt; 0</code>");
> +    }
> +
> +}
>
> Regards,
> Masanori Yano