--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/taglet/Taglet.java Tue Mar 07 08:43:29 2017 -0800
+++ b/langtools/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/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/UserTaglet.java Tue Mar 07 08:43:29 2017 -0800
+++ b/langtools/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/langtools/test/jdk/javadoc/doclet/testLegacyTaglet/TestLegacyTaglet.java Tue Mar 07 08:43:29 2017 -0800
+++ b/langtools/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/langtools/test/jdk/javadoc/doclet/testLegacyTaglet/ToDoTaglet.java Tue Mar 07 08:43:29 2017 -0800
+++ b/langtools/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/langtools/test/jdk/javadoc/doclet/testLegacyTaglet/UnderlineTaglet.java Tue Mar 07 08:43:29 2017 -0800
+++ b/langtools/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/langtools/test/jdk/javadoc/tool/EnsureNewOldDoclet.java Tue Mar 07 08:43:29 2017 -0800
+++ b/langtools/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/langtools/test/jdk/javadoc/tool/api/basic/taglets/UnderlineTaglet.java Tue Mar 07 08:43:29 2017 -0800
+++ b/langtools/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) {