Mercurial > hg > openjdk > jdk9 > langtools

changeset 4023:f183296d126b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
8176131: Simplify new Taglet API Reviewed-by: ksrini
author jjg
date Tue, 07 Mar 2017 15:20:43 -0800
parents 17249d1d92fe
children 917615c2abd9
files src/jdk.javadoc/share/classes/jdk/javadoc/doclet/taglet/Taglet.java src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/UserTaglet.java test/jdk/javadoc/doclet/testLegacyTaglet/TestLegacyTaglet.java test/jdk/javadoc/doclet/testLegacyTaglet/ToDoTaglet.java test/jdk/javadoc/doclet/testLegacyTaglet/UnderlineTaglet.java test/jdk/javadoc/tool/EnsureNewOldDoclet.java test/jdk/javadoc/tool/api/basic/taglets/UnderlineTaglet.java
diffstat 7 files changed, 40 insertions(+), 80 deletions(-) [+]
line wrap: on
line diff
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/taglet/Taglet.java	Tue Mar 07 08:43:29 2017 -0800
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/taglet/Taglet.java	Tue Mar 07 15:20:43 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 2017, 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
@@ -31,11 +31,15 @@
 import com.sun.source.doctree.DocTree;
 
 /**
- * The interface for a custom tag used by Doclets. A custom
- * tag must implement this interface, and must have a public
- * default constructor (i.e. a public constructor with no
+ * The interface for a custom taglet supported by doclets such as
+ * the {@link jdk.javadoc.doclets.StandardDoclet standard doclet}.
+ * Custom taglets are used to handle custom tags in documentation
+ * comments.
+ *
+ * <p>A custom taglet must implement this interface, and must have
+ * a public default constructor (i.e. a public constructor with no
  * parameters), by which, the doclet will instantiate and
- * register the custom tag.
+ * register the custom taglet.
  *
  * @since 9
  */
@@ -43,16 +47,14 @@
 public interface Taglet {
 
     /**
-     * Returns the set of locations in which a taglet may be used.
-     * @return the set of locations in which a taglet may be used
-     * allowed in or an empty set.
+     * Returns the set of locations in which a tag may be used.
+     * @return the set of locations in which a tag may be used
      */
     Set<Location> getAllowedLocations();
 
     /**
-     * Indicates the tag is an inline or a body tag.
-     * @return true if this <code>Taglet</code>
-     * is an inline tag, false otherwise.
+     * Indicates whether this taglet is for inline tags or not.
+     * @return true if this taglet is for an inline tag, and false otherwise
      */
     boolean isInlineTag();
 
@@ -63,26 +65,21 @@
     String getName();
 
     /**
-     * Given the {@link DocTree DocTree} representation of this custom
-     * tag, return its string representation, which is output
-     * to the generated page.
-     * @param tag the <code>Tag</code> representation of this custom tag.
-     * @return the string representation of this <code>Tag</code>.
-     */
-    String toString(DocTree tag);
-
-    /**
-     * Given a List of {@link DocTree DocTrees} representing this custom
-     * tag, return its string representation, which is output
-     * to the generated page.  This method should
-     * return null if this taglet represents an inline or body tag.
-     * @param tags the list of <code>DocTree</code>s representing this custom tag.
-     * @return the string representation of this <code>Tag</code>.
+     * Returns the string representation of a series of instances of
+     * this tag to be included in the generated output.
+     * If this taglet is for an {@link #isInlineTag inline} tag} it will
+     * be called once per instance of the tag, each time with a singleton list.
+     * Otherwise, if this tag is a block tag, it will be called once per
+     * comment, with a list of all the instances of the tag in the comment.
+     * @param tags the list of {@code DocTree} containing one or more
+     *  instances of this tag
+     * @return the string representation of the tags to be included in
+     *  the generated output
      */
     String toString(List<? extends DocTree> tags);
 
     /**
-     * The kind of location.
+     * The kind of location in which a tag may be used.
      */
     public static enum Location {
         /** In an Overview document. */
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/UserTaglet.java	Tue Mar 07 08:43:29 2017 -0800
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/UserTaglet.java	Tue Mar 07 15:20:43 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2017, 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
@@ -24,6 +24,7 @@
  */
 package jdk.javadoc.internal.doclets.toolkit.taglets;
 
+import java.util.Collections;
 import java.util.List;
 
 import javax.lang.model.element.Element;
@@ -131,7 +132,7 @@
      */
     public Content getTagletOutput(Element element, DocTree tag, TagletWriter writer){
         Content output = writer.getOutputInstance();
-        output.addContent(new RawHtml(userTaglet.toString(tag)));
+        output.addContent(new RawHtml(userTaglet.toString(Collections.singletonList(tag))));
         return output;
     }
 
--- a/test/jdk/javadoc/doclet/testLegacyTaglet/TestLegacyTaglet.java	Tue Mar 07 08:43:29 2017 -0800
+++ b/test/jdk/javadoc/doclet/testLegacyTaglet/TestLegacyTaglet.java	Tue Mar 07 15:20:43 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2017, 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
@@ -23,7 +23,7 @@
 
 /*
  * @test
- * @bug 4638723 8015882
+ * @bug 4638723 8015882 8176131
  * @summary Test to ensure that the refactored version of the standard
  * doclet still works with Taglets that implement the 1.4.0 interface.
  * @author jamieh
--- a/test/jdk/javadoc/doclet/testLegacyTaglet/ToDoTaglet.java	Tue Mar 07 08:43:29 2017 -0800
+++ b/test/jdk/javadoc/doclet/testLegacyTaglet/ToDoTaglet.java	Tue Mar 07 15:20:43 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2017, 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
@@ -84,19 +84,6 @@
     }
 
     /**
-     * Given the <code>DocTree</code> representation of this custom
-     * tag, return its string representation.
-     * @param tag   the <code>DocTree</code> representing this custom tag.
-     */
-    public String toString(DocTree tag) {
-
-        return "<DT><B>" + HEADER + "</B><DD>"
-               + "<table summary=\"Summary\" cellpadding=2 cellspacing=0><tr><td bgcolor=\"yellow\">"
-               + getText(tag)
-               + "</td></tr></table></DD>\n";
-    }
-
-    /**
      * Given an array of <code>Tag</code>s representing this custom
      * tag, return its string representation.
      * @param tags  the array of <code>DocTree</code>s representing this custom tag.
@@ -104,7 +91,7 @@
     @Override
     public String toString(List<? extends DocTree> tags) {
         if (tags.isEmpty()) {
-            return null;
+            return "";
         }
         String result = "\n<DT><B>" + HEADER + "</B><DD>";
         result += "<table summary=\"Summary\" cellpadding=2 cellspacing=0><tr><td bgcolor=\"yellow\">";
--- a/test/jdk/javadoc/doclet/testLegacyTaglet/UnderlineTaglet.java	Tue Mar 07 08:43:29 2017 -0800
+++ b/test/jdk/javadoc/doclet/testLegacyTaglet/UnderlineTaglet.java	Tue Mar 07 15:20:43 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2017, 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
@@ -69,20 +69,10 @@
     /**
      * Given the <code>DocTree</code> representation of this custom
      * tag, return its string representation.
-     * @param tag he <code>DocTree</code> representation of this custom tag.
-     */
-    @Override
-    public String toString(DocTree tag) {
-        return "<u>" + ToDoTaglet.getText(tag) + "</u>";
-    }
-
-    /**
-     * This method should not be called since arrays of inline tags do not
-     * exist.  Method {@link #tostring(DocTree)} should be used to convert this
-     * inline tag to a string.
+     * @param tags the <code>DocTree</code> representation of this custom tag.
      */
     @Override
     public String toString(List<? extends DocTree> tags) {
-        return null;
+        return "<u>" + ToDoTaglet.getText(tags.get(0)) + "</u>";
     }
 }
--- a/test/jdk/javadoc/tool/EnsureNewOldDoclet.java	Tue Mar 07 08:43:29 2017 -0800
+++ b/test/jdk/javadoc/tool/EnsureNewOldDoclet.java	Tue Mar 07 15:20:43 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2017, 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
@@ -23,7 +23,7 @@
 
 /*
  * @test
- * @bug 8035473 8154482 8154399 8159096
+ * @bug 8035473 8154482 8154399 8159096 8176131
  * @summary make sure the javadoc tool responds correctly to Xold,
  *          old doclets and taglets.
  * @library /tools/lib
@@ -358,11 +358,6 @@
         }
 
         @Override
-        public String toString(DocTree tag) {
-            return tag.toString();
-        }
-
-        @Override
         public String toString(List<? extends DocTree> tags) {
             return tags.toString();
         }
--- a/test/jdk/javadoc/tool/api/basic/taglets/UnderlineTaglet.java	Tue Mar 07 08:43:29 2017 -0800
+++ b/test/jdk/javadoc/tool/api/basic/taglets/UnderlineTaglet.java	Tue Mar 07 15:20:43 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2002, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2002, 2017, Oracle and/or its affiliates. All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or
  * without modification, are permitted provided that the following
@@ -85,22 +85,12 @@
     }
 
     /**
-     * Given the <code>Tag</code> representation of this custom
+     * Given the <code>DocTree</code> representation of this custom
      * tag, return its string representation.
-     * @param tag he <code>Tag</code> representation of this custom tag.
-     */
-    public String toString(DocTree tag) {
-        return "<u>" + getText(tag) + "</u>";
-    }
-
-    /**
-     * This method should not be called since arrays of inline tags do not
-     * exist.  Method {@link #tostring(Tag)} should be used to convert this
-     * inline tag to a string.
-     * @param tags the array of <code>Tag</code>s representing of this custom tag.
+     * @param tags the list of trees representing of this custom tag.
      */
     public String toString(List<? extends DocTree> tags) {
-        return null;
+        return "<u>" + getText(tags.get(0)) + "</u>";
     }
 
     static String getText(DocTree dt) {