8238506: fix obsolete comments and inconsistent exceptions in BaseTaglet

Reviewed-by: prappo

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

@@ -49,23 +49,13 @@ public BasePropertyTaglet(String name) {
     }
 
     /**
-     * This method returns the text to be put in the resulting javadoc before
-     * the property name.
+     * Returns the text to be included in the documentation before the property name.
      *
-     * @param tagletWriter the taglet writer for output
-     * @return the string to be put in the resulting javadoc.
+     * @param tagletWriter the taglet-writer used by the doclet
+     * @return the text to be included in the documentation before the property name
      */
     abstract String getText(TagletWriter tagletWriter);
 
-    /**
-     * Given the <code>Tag</code> representation of this custom
-     * tag, return its string representation, which is output
-     * to the generated page.
-     * @param element
-     * @param tag the <code>Tag</code> representation of this custom tag.
-     * @param tagletWriter the taglet writer for output.
-     * @return the TagletOutput representation of this <code>Tag</code>.
-     */
     @Override
     public Content getTagletOutput(Element element, DocTree tag, TagletWriter tagletWriter) {
         return tagletWriter.propertyTagOutput(element, tag, getText(tagletWriter));

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

@@ -188,11 +188,21 @@ public boolean accepts(DocTree tree) {
                 : tree.getKind() == tagKind;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @implSpec This implementation throws {@link UnsupportedTagletOperationException}.
+     */
     @Override
     public Content getTagletOutput(Element element, DocTree tag, TagletWriter writer) {
         throw new UnsupportedTagletOperationException("Method not supported in taglet " + getName() + ".");
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @implSpec This implementation throws {@link UnsupportedTagletOperationException}
+     */
     @Override
     public Content getTagletOutput(Element holder, TagletWriter writer) {
         throw new UnsupportedTagletOperationException("Method not supported in taglet " + getName() + ".");

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2020, 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
@@ -135,29 +135,28 @@ default boolean isBlockTag() {
     String getName();
 
     /**
-     * Given the <code>Tag</code> representation of this custom
-     * tag, return its Content representation, which is output
-     * to the generated page.
-     * @param holder the element holding the tag
-     * @param tag the <code>Tag</code> representation of this custom tag.
-     * @param writer a {@link TagletWriter} Taglet writer.
-     * @throws UnsupportedOperationException thrown when the method is not supported by the taglet.
-     * @return the Content representation of this <code>Tag</code>.
+     * Returns the content to be included in the generated output for an
+     * instance of a tag handled by this taglet.
+     *
+     * @param element the element for the enclosing doc comment
+     * @param tag     the tag
+     * @param writer  the taglet-writer used in this doclet
+     * @return the output for this tag
+     * @throws UnsupportedTagletOperationException thrown when the method is not supported by the taglet
      */
-    Content getTagletOutput(Element holder, DocTree tag, TagletWriter writer) throws
-            UnsupportedOperationException;
+    Content getTagletOutput(Element element, DocTree tag, TagletWriter writer) throws
+            UnsupportedTagletOperationException;
 
     /**
-     * Given an element object, check if it holds any tags of
-     * this type.  If it does, return the content representing the output.
-     * If it does not, return null.
-     * @param holder an element holding the custom tag.
-     * @param writer a {@link TagletWriter} Taglet writer.
-     * @throws UnsupportedTagletOperationException thrown when the method is not
-     *         supported by the taglet.
-     * @return the content representation of this <code>Tag</code>.
+     * Returns the content to be included in the generated output for all
+     * instances of tags handled by this taglet.
+     *
+     * @param element the element for the enclosing doc comment
+     * @param writer  the taglet-writer used in this doclet
+     * @return the output for this tag
+     * @throws UnsupportedTagletOperationException thrown when the method is not supported by the taglet
      */
-    Content getTagletOutput(Element holder, TagletWriter writer) throws
+    Content getTagletOutput(Element element, TagletWriter writer) throws
             UnsupportedTagletOperationException;
 
     class UnsupportedTagletOperationException extends UnsupportedOperationException {

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

@@ -77,21 +77,20 @@ public void inherit(DocFinder.Input input, DocFinder.Output output) {
                     ? ch.getExceptionName(input.docTreeInfo.docTree).getSignature()
                     : utils.getFullyQualifiedName(exception);
         } else {
-            TypeElement element = input.utils.findClass(input.element, input.tagId);
-            exception = (element == null) ? null : element;
+            exception = input.utils.findClass(input.element, input.tagId);
         }
 
         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))))) {
+            Element exc = ch.getException(utils.configuration, dt);
+            if (exc != null && (input.tagId.equals(utils.getSimpleName(exc)) ||
+                 (input.tagId.equals(utils.getFullyQualifiedName(exc))))) {
                 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)) {
+            } else if (exception != null && exc != null &&
+                    utils.isTypeElement(exc) && utils.isTypeElement(exception) &&
+                    utils.isSubclassOf((TypeElement)exc, (TypeElement)exception)) {
                 output.tagList.add(dt);
             }
         }
@@ -106,15 +105,15 @@ private Content linkToUndocumentedDeclaredExceptions(List<? extends TypeMirror>
         Content result = writer.getOutputInstance();
         //Add links to the exceptions declared but not documented.
         for (TypeMirror declaredExceptionType : declaredExceptionTypes) {
-            TypeElement klass = utils.asTypeElement(declaredExceptionType);
-            if (klass != null &&
+            TypeElement te = utils.asTypeElement(declaredExceptionType);
+            if (te != null &&
                 !alreadyDocumented.contains(declaredExceptionType.toString()) &&
-                !alreadyDocumented.contains(utils.getFullyQualifiedName(klass, false))) {
+                !alreadyDocumented.contains(utils.getFullyQualifiedName(te, false))) {
                 if (alreadyDocumented.isEmpty()) {
                     result.add(writer.getThrowsHeader());
                 }
                 result.add(writer.throwsTagOutput(declaredExceptionType));
-                alreadyDocumented.add(utils.getSimpleName(klass));
+                alreadyDocumented.add(utils.getSimpleName(te));
             }
         }
         return result;
@@ -176,18 +175,17 @@ public Content getTagletOutput(Element holder, TagletWriter writer) {
     }
 
     /**
-     * Given an array of <code>Tag</code>s representing this custom
-     * tag, return its string representation.
-     * @param throwTags the array of <code>ThrowsTag</code>s to convert.
-     * @param writer the TagletWriter that will write this tag.
-     * @param alreadyDocumented the set of exceptions that have already
-     *        been documented.
-     * @param allowDups True if we allow duplicate throws tags to be documented.
-     * @return the Content representation of this <code>Tag</code>.
+     * Returns the generated content for a collection of {@code @throws} tags.
+     *
+     * @param throwTags         the collection of tags to be converted
+     * @param writer            the taglet-writer used by the doclet
+     * @param alreadyDocumented the set of exceptions that have already been documented
+     * @param allowDuplicates   {@code true} if we allow duplicate tags to be documented
+     * @return the generated content for the tags
      */
     protected Content throwsTagsOutput(Map<List<? extends DocTree>, ExecutableElement> throwTags,
                                        TagletWriter writer, Set<String> alreadyDocumented,
-                                       Map<String,TypeMirror> typeSubstitutions, boolean allowDups) {
+                                       Map<String,TypeMirror> typeSubstitutions, boolean allowDuplicates) {
         Utils utils = writer.configuration().utils;
         Content result = writer.getOutputInstance();
         if (!throwTags.isEmpty()) {
@@ -198,7 +196,7 @@ protected Content throwsTagsOutput(Map<List<? extends DocTree>, ExecutableElemen
                     Element te = ch.getException(utils.configuration, dt);
                     String excName = ch.getExceptionName(dt).toString();
                     TypeMirror substituteType = typeSubstitutions.get(excName);
-                    if ((!allowDups) &&
+                    if ((!allowDuplicates) &&
                         (alreadyDocumented.contains(excName) ||
                         (te != null && alreadyDocumented.contains(utils.getFullyQualifiedName(te, false)))) ||
                         (substituteType != null && alreadyDocumented.contains(substituteType.toString()))) {

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java

@@ -399,14 +399,14 @@ private Result begin(List<String> options, Iterable<? extends JavaFileObject> fi
             Throwable t = e.getCause();
             dumpStack(t == null ? e : t);
             return ERROR;
-        } catch (OptionException toe) {
-            if (toe.message != null)
-                messager.printError(toe.message);
-
-            toe.m.run();
-            Throwable t = toe.getCause();
-            dumpStack(t == null ? toe : t);
-            return toe.result;
+        } catch (OptionException oe) {
+            if (oe.message != null)
+                messager.printError(oe.message);
+
+            oe.m.run();
+            Throwable t = oe.getCause();
+            dumpStack(t == null ? oe : t);
+            return oe.result;
         } catch (ToolException exc) {
             if (exc.message != null) {
                 messager.printError(exc.message);