stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8176131: Simplify new Taglet API

Browse Source 
Reviewed-by: ksrini
This commit is contained in:
Jonathan Gibbons 2017-03-07 15:20:43 -08:00
parent 683950a9eb
commit 558b587367
7 changed files with 40 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/taglet/Taglet.java
View File

@ -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 java.util.Set;
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 @@ import com.sun.source.doctree.DocTree;
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 @@ public interface Taglet {
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. */

5
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/UserTaglet.java
View File

@ -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 class UserTaglet implements Taglet {
*/
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;
}

4
langtools/test/jdk/javadoc/doclet/testLegacyTaglet/TestLegacyTaglet.java
View File

@ -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

17
langtools/test/jdk/javadoc/doclet/testLegacyTaglet/ToDoTaglet.java
View File

@ -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
@ -83,19 +83,6 @@ public class ToDoTaglet implements Taglet {
return false;
}
/**
* 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.
@ -104,7 +91,7 @@ public class ToDoTaglet implements Taglet {
@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\">";

16
langtools/test/jdk/javadoc/doclet/testLegacyTaglet/UnderlineTaglet.java
View File

@ -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 @@ public class UnderlineTaglet implements Taglet {
/**
* 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>";
}
}

9
langtools/test/jdk/javadoc/tool/EnsureNewOldDoclet.java
View File

@ -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
@ -357,11 +357,6 @@ public class EnsureNewOldDoclet extends TestRunner {
return "NewTaglet";
}
@Override
public String toString(DocTree tag) {
return tag.toString();
}
@Override
public String toString(List<? extends DocTree> tags) {
return tags.toString();

18
langtools/test/jdk/javadoc/tool/api/basic/taglets/UnderlineTaglet.java
View File

@ -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 @@ public class UnderlineTaglet implements Taglet {
}
/**
* 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) {