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

8202947: Fix minor issues with taglets

Browse Source 
Reviewed-by: ksrini
This commit is contained in:
Jonathan Gibbons 2018-05-23 11:49:57 -07:00
parent 751d742516
commit d27d4d8df4
34 changed files with 757 additions and 1120 deletions

3
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java

@ -44,7 +44,6 @@ import jdk.javadoc.doclet.DocletEnvironment;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlVersion;
import jdk.javadoc.internal.doclets.formats.html.markup.Links;
import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration;
import jdk.javadoc.internal.doclets.toolkit.Content;
import jdk.javadoc.internal.doclets.toolkit.DocletException;
@ -367,7 +366,7 @@ public class HtmlConfiguration extends BaseConfiguration {
docPaths = new DocPaths(utils, useModuleDirectories);
setCreateOverview();
setTopFile(docEnv);
workArounds.initDocLint(doclintOpts.values(), tagletManager.getCustomTagNames(),
workArounds.initDocLint(doclintOpts.values(), tagletManager.getAllTagletNames(),
Utils.toLowerCase(htmlVersion.name()));
return true;
}

6
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java

@ -332,7 +332,7 @@ public class HtmlDocletWriter {
}
Content output = new ContentBuilder();
TagletWriter.genTagOutput(configuration.tagletManager, e,
configuration.tagletManager.getCustomTaglets(e),
configuration.tagletManager.getBlockTaglets(e),
getTagletWriterInstance(false), output);
dl.addContent(output);
htmltree.addContent(dl);
@ -348,7 +348,7 @@ public class HtmlDocletWriter {
protected boolean hasSerializationOverviewTags(VariableElement field) {
Content output = new ContentBuilder();
TagletWriter.genTagOutput(configuration.tagletManager, field,
configuration.tagletManager.getCustomTaglets(field),
configuration.tagletManager.getBlockTaglets(field),
getTagletWriterInstance(false), output);
return !output.isEmpty();
}
@ -1301,7 +1301,7 @@ public class HtmlDocletWriter {
};
CommentHelper ch = utils.getCommentHelper(element);
// Array of all possible inline tags for this javadoc run
configuration.tagletManager.checkTags(utils, element, tags, true);
configuration.tagletManager.checkTags(element, tags, true);
commentRemoved = false;
for (ListIterator<? extends DocTree> iterator = tags.listIterator(); iterator.hasNext();) {

4
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlSerialFieldWriter.java

@ -1,5 +1,5 @@
/*
* Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1998, 2018, 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
@ -200,7 +200,7 @@ public class HtmlSerialFieldWriter extends FieldWriterImpl
public void addMemberTags(VariableElement field, Content contentTree) {
Content tagContent = new ContentBuilder();
TagletWriter.genTagOutput(configuration.tagletManager, field,
configuration.tagletManager.getCustomTaglets(field),
configuration.tagletManager.getBlockTaglets(field),
writer.getTagletWriterInstance(false), tagContent);
Content dlTags = new HtmlTree(HtmlTag.DL);
dlTags.addContent(tagContent);

59
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseConfiguration.java

@ -352,6 +352,11 @@ public abstract class BaseConfiguration {
*/
public boolean disableJavaFxStrictChecks = false;
/**
* Show taglets (internal debug switch)
*/
public boolean showTaglets = false;
VisibleMemberCache visibleMemberCache = null;
public PropertyUtils propertyUtils = null;
@ -727,7 +732,14 @@ public abstract class BaseConfiguration {
disableJavaFxStrictChecks = true;
return true;
}
}
},
new Hidden(resources, "--show-taglets") {
@Override
public boolean process(String opt, List<String> args) {
showTaglets = true;
return true;
}
},
};
Set<Doclet.Option> set = new TreeSet<>();
set.addAll(Arrays.asList(options));
@ -814,25 +826,32 @@ public abstract class BaseConfiguration {
continue;
}
List<String> tokens = tokenize(args.get(1), TagletManager.SIMPLE_TAGLET_OPT_SEPARATOR, 3);
if (tokens.size() == 1) {
String tagName = args.get(1);
if (tagletManager.isKnownCustomTag(tagName)) {
//reorder a standard tag
tagletManager.addNewSimpleCustomTag(tagName, null, "");
} else {
//Create a simple tag with the heading that has the same name as the tag.
StringBuilder heading = new StringBuilder(tagName + ":");
heading.setCharAt(0, Character.toUpperCase(tagName.charAt(0)));
tagletManager.addNewSimpleCustomTag(tagName, heading.toString(), "a");
}
} else if (tokens.size() == 2) {
//Add simple taglet without heading, probably to excluding it in the output.
tagletManager.addNewSimpleCustomTag(tokens.get(0), tokens.get(1), "");
} else if (tokens.size() >= 3) {
tagletManager.addNewSimpleCustomTag(tokens.get(0), tokens.get(2), tokens.get(1));
} else {
Messages messages = getMessages();
messages.error("doclet.Error_invalid_custom_tag_argument", args.get(1));
switch (tokens.size()) {
case 1:
String tagName = args.get(1);
if (tagletManager.isKnownCustomTag(tagName)) {
//reorder a standard tag
tagletManager.addNewSimpleCustomTag(tagName, null, "");
} else {
//Create a simple tag with the heading that has the same name as the tag.
StringBuilder heading = new StringBuilder(tagName + ":");
heading.setCharAt(0, Character.toUpperCase(tagName.charAt(0)));
tagletManager.addNewSimpleCustomTag(tagName, heading.toString(), "a");
}
break;
case 2:
//Add simple taglet without heading, probably to excluding it in the output.
tagletManager.addNewSimpleCustomTag(tokens.get(0), tokens.get(1), "");
break;
case 3:
tagletManager.addNewSimpleCustomTag(tokens.get(0), tokens.get(2), tokens.get(1));
break;
default:
Messages messages = getMessages();
messages.error("doclet.Error_invalid_custom_tag_argument", args.get(1));
}
}
}

1
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties

@ -172,7 +172,6 @@ doclet.Method_Detail=Method Detail
doclet.Constructor_Detail=Constructor Detail
doclet.Deprecated=Deprecated.
doclet.DeprecatedForRemoval=Deprecated, for removal: This API element is subject to removal in a future version.
doclet.Hidden=Hidden
doclet.Groupname_already_used=In -group option, groupname already used: {0}
doclet.value_tag_invalid_reference={0} (referenced by @value tag) is an unknown reference.
doclet.value_tag_invalid_constant=@value tag (which references {0}) can only be used in constants.

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

@ -1,105 +0,0 @@
/*
* Copyright (c) 2001, 2016, 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package jdk.javadoc.internal.doclets.toolkit.taglets;
/**
* An abstract class for that implements the {@link Taglet} interface
* for tags in <code>ExecutableMembers</code>.
*
* <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>
*
* @author Jamie Ho
*/
public abstract class BaseExecutableMemberTaglet extends BaseTaglet {
/**
* Return true if this <code>Taglet</code>
* is used in field documentation.
* @return true if this <code>Taglet</code>
* is used in field documentation and false
* otherwise.
*/
public boolean inField() {
return false;
}
/**
* Return true if this <code>Taglet</code>
* is used in overview documentation.
* @return true if this <code>Taglet</code>
* is used in overview documentation and false
* otherwise.
*/
public boolean inOverview() {
return false;
}
/**
* Return true if this <code>Taglet</code>
* is used in module documentation.
* @return true if this <code>Taglet</code>
* is used in module documentation and false
* otherwise.
*/
public boolean inModule() {
return false;
}
/**
* Return true if this <code>Taglet</code>
* is used in package documentation.
* @return true if this <code>Taglet</code>
* is used in package documentation and false
* otherwise.
*/
public boolean inPackage() {
return false;
}
/**
* Return true if this <code>Taglet</code>
* is used in type documentation (classes or interfaces).
* @return true if this <code>Taglet</code>
* is used in type documentation and false
* otherwise.
*/
public boolean inType() {
return false;
}
/**
* Return true if this <code>Taglet</code>
* is an inline tag.
* @return true if this <code>Taglet</code>
* is an inline tag and false otherwise.
*/
public boolean isInlineTag() {
return false;
}
}

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

@ -1,48 +0,0 @@
/*
* Copyright (c) 2001, 2016, 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package jdk.javadoc.internal.doclets.toolkit.taglets;
/**
* An abstract inline taglet that outputs HTML.
*
* <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>
*
* @author Jamie Ho
*/
public abstract class BaseInlineTaglet extends BaseTaglet {
/**
* Will return true since this is an inline tag.
* @return true since this is an inline tag.
*/
public boolean isInlineTag() {
return true;
}
}

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2015, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2018, 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
@ -25,6 +25,7 @@
package jdk.javadoc.internal.doclets.toolkit.taglets;
import java.util.EnumSet;
import javax.lang.model.element.Element;
import com.sun.source.doctree.DocTree;
@ -42,7 +43,8 @@ import jdk.javadoc.internal.doclets.toolkit.Content;
*/
public abstract class BasePropertyTaglet extends BaseTaglet {
public BasePropertyTaglet() {
public BasePropertyTaglet(String name) {
super(name, false, EnumSet.of(Site.METHOD));
}
/**
@ -66,58 +68,4 @@ public abstract class BasePropertyTaglet extends BaseTaglet {
public Content getTagletOutput(Element element, DocTree tag, TagletWriter tagletWriter) {
return tagletWriter.propertyTagOutput(element, tag, getText(tagletWriter));
}
/**
* Will return false because this tag may
* only appear in Methods.
* @return false since this is not a method.
*/
public boolean inConstructor() {
return false;
}
/**
* Will return false because this tag may
* only appear in Methods.
* @return false since this is not a method.
*/
public boolean inOverview() {
return false;
}
/**
* Will return false because this tag may
* only appear in Methods.
* @return false since this is not a method.
*/
public boolean inModule() {
return false;
}
/**
* Will return false because this tag may
* only appear in Methods.
* @return false since this is not a method.
*/
public boolean inPackage() {
return false;
}
/**
* Will return false because this tag may
* only appear in Methods.
* @return false since this is not a method.
*/
public boolean inType() {
return false;
}
/**
* Will return false because this tag is not inline.
* @return false since this is not an inline tag.
*/
public boolean isInlineTag() {
return false;
}
}

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2018, 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
@ -25,13 +25,14 @@
package jdk.javadoc.internal.doclets.toolkit.taglets;
import java.util.Set;
import javax.lang.model.element.Element;
import com.sun.source.doctree.DocTree;
import jdk.javadoc.internal.doclets.toolkit.Content;
/**
* An abstract class for that implements the {@link Taglet} interface.
* A base class that implements the {@link Taglet} interface.
*
* <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.
@ -40,100 +41,98 @@ import jdk.javadoc.internal.doclets.toolkit.Content;
*
* @author Jamie Ho
*/
public abstract class BaseTaglet implements Taglet {
public class BaseTaglet implements Taglet {
/**
* The different kinds of place where any given tag may be used.
*/
enum Site {
OVERVIEW, MODULE, PACKAGE, TYPE, CONSTRUCTOR, METHOD, FIELD
}
protected String name = "Default";
protected final String name;
private final boolean inline;
private final Set<Site> sites;
BaseTaglet(String name, boolean inline, Set<Site> sites) {
this.name = name;
this.inline = inline;
this.sites = sites;
}
/**
* Return true if this <code>Taglet</code>
* is used in constructor documentation.
* @return true if this <code>Taglet</code>
* is used in constructor documentation and false
* Returns true if this {@code Taglet} can be used in constructor documentation.
* @return true if this {@code Taglet} can be used in constructor documentation and false
* otherwise.
*/
public boolean inConstructor() {
return true;
public final boolean inConstructor() {
return sites.contains(Site.CONSTRUCTOR);
}
/**
* Return true if this <code>Taglet</code>
* is used in field documentation.
* @return true if this <code>Taglet</code>
* is used in field documentation and false
* Returns true if this {@code Taglet} can be used in field documentation.
* @return true if this {@code Taglet} can be used in field documentation and false
* otherwise.
*/
public boolean inField() {
return true;
public final boolean inField() {
return sites.contains(Site.FIELD);
}
/**
* Return true if this <code>Taglet</code>
* is used in method documentation.
* @return true if this <code>Taglet</code>
* is used in method documentation and false
* Returns true if this {@code Taglet} can be used in method documentation.
* @return true if this {@code Taglet} can be used in method documentation and false
* otherwise.
*/
public boolean inMethod() {
return true;
public final boolean inMethod() {
return sites.contains(Site.METHOD);
}
/**
* Return true if this <code>Taglet</code>
* is used in overview documentation.
* @return true if this <code>Taglet</code>
* is used in method documentation and false
* Returns true if this {@code Taglet} can be used in overview documentation.
* @return true if this {@code Taglet} can be used in method documentation and false
* otherwise.
*/
public boolean inOverview() {
return true;
public final boolean inOverview() {
return sites.contains(Site.OVERVIEW);
}
/**
* Return true if this <code>Taglet</code>
* is used in module documentation.
* @return true if this <code>Taglet</code>
* is used in module documentation and false
* Returns true if this {@code Taglet} can be used in module documentation.
* @return true if this {@code Taglet} can be used in module documentation and false
* otherwise.
*/
public boolean inModule() {
return true;
public final boolean inModule() {
return sites.contains(Site.MODULE);
}
/**
* Return true if this <code>Taglet</code>
* is used in package documentation.
* @return true if this <code>Taglet</code>
* is used in package documentation and false
* Returns true if this {@code Taglet} can be used in package documentation.
* @return true if this {@code Taglet} can be used in package documentation and false
* otherwise.
*/
public boolean inPackage() {
return true;
public final boolean inPackage() {
return sites.contains(Site.PACKAGE);
}
/**
* Return true if this <code>Taglet</code>
* is used in type documentation (classes or interfaces).
* @return true if this <code>Taglet</code>
* is used in type documentation and false
* Returns true if this {@code Taglet} can be used in type documentation (classes or interfaces).
* @return true if this {@code Taglet} can be used in type documentation and false
* otherwise.
*/
public boolean inType() {
return true;
public final boolean inType() {
return sites.contains(Site.TYPE);
}
/**
* Return true if this <code>Taglet</code>
* is an inline tag.
* @return true if this <code>Taglet</code>
* is an inline tag and false otherwise.
* Returns true if this {@code Taglet} is an inline tag.
* @return true if this {@code Taglet} represents an inline tag and false otherwise.
*/
public boolean isInlineTag() {
return false;
public final boolean isInlineTag() {
return inline;
}
/**
* Return the name of this custom tag.
* @return the name of this custom tag.
* Returns the name of this tag.
* @return the name of this tag.
*/
public String getName() {
return name;

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2018, 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
@ -25,14 +25,14 @@
package jdk.javadoc.internal.doclets.toolkit.taglets;
import java.util.Map;
import java.util.EnumSet;
import javax.lang.model.element.Element;
import com.sun.source.doctree.DocTree;
import jdk.javadoc.internal.doclets.toolkit.Content;
import static com.sun.source.doctree.DocTree.Kind.*;
import static com.sun.source.doctree.DocTree.Kind.CODE;
/**
* An inline Taglet used to denote literal code fragments.
@ -54,17 +54,13 @@ import static com.sun.source.doctree.DocTree.Kind.*;
* @author Scott Seligman
*/
public class CodeTaglet extends BaseInlineTaglet {
public class CodeTaglet extends BaseTaglet {
private static final String NAME = CODE.tagName;
public String getName() {
return NAME;
CodeTaglet() {
super(CODE.tagName, true, EnumSet.allOf(Site.class));
}
/**
* {@inheritDoc}
*/
@Override
public Content getTagletOutput(Element element, DocTree tag, TagletWriter writer) {
return writer.codeTagOutput(element, tag);
}

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2018, 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
@ -25,12 +25,13 @@
package jdk.javadoc.internal.doclets.toolkit.taglets;
import java.util.EnumSet;
import javax.lang.model.element.Element;
import com.sun.source.doctree.DocTree;
import jdk.javadoc.internal.doclets.toolkit.Content;
import static com.sun.source.doctree.DocTree.Kind.*;
import static com.sun.source.doctree.DocTree.Kind.DEPRECATED;
/**
* A taglet that represents the @deprecated tag.
@ -43,15 +44,14 @@ import static com.sun.source.doctree.DocTree.Kind.*;
* @author Jamie Ho
*/
public class DeprecatedTaglet extends BaseTaglet{
public class DeprecatedTaglet extends BaseTaglet {
public DeprecatedTaglet() {
name = DEPRECATED.tagName;
super(DEPRECATED.tagName, false,
EnumSet.of(Site.MODULE, Site.TYPE, Site.CONSTRUCTOR, Site.METHOD, Site.FIELD));
}
/**
* {@inheritDoc}
*/
@Override
public Content getTagletOutput(Element holder, TagletWriter writer) {
return writer.deprecatedTagOutput(holder);
}

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2018, 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
@ -25,12 +25,13 @@
package jdk.javadoc.internal.doclets.toolkit.taglets;
import java.util.EnumSet;
import javax.lang.model.element.Element;
import com.sun.source.doctree.DocTree;
import jdk.javadoc.internal.doclets.toolkit.Content;
import static com.sun.source.doctree.DocTree.Kind.*;
import static com.sun.source.doctree.DocTree.Kind.DOC_ROOT;
/**
* An inline Taglet representing {&#064;docRoot}. This taglet is
@ -46,25 +47,16 @@ import static com.sun.source.doctree.DocTree.Kind.*;
* @author Doug Kramer
*/
public class DocRootTaglet extends BaseInlineTaglet {
public class DocRootTaglet extends BaseTaglet {
/**
* Construct a new DocRootTaglet.
*/
public DocRootTaglet() {
name = DOC_ROOT.tagName;
super(DOC_ROOT.tagName, true, EnumSet.allOf(Site.class));
}
/**
* Given a <code>Doc</code> object, check if it holds any tags of
* this type. If it does, return the string representing the output.
* If it does not, return null.
* @param holder
* @param tag a tag representing the custom tag.
* @param writer a {@link TagletWriter} Taglet writer.
* @return the string representation of this <code>Tag</code>.
*/
@Override
public Content getTagletOutput(Element holder, DocTree tag, TagletWriter writer) {
return writer.getDocRootOutput();
}

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

@ -1,56 +0,0 @@
/*
* Copyright (c) 2016, 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package jdk.javadoc.internal.doclets.toolkit.taglets;
import javax.lang.model.element.Element;
import jdk.javadoc.internal.doclets.toolkit.Content;
import static com.sun.source.doctree.DocTree.Kind.*;
/**
* A taglet that represents the @hidden 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 HiddenTaglet extends BaseTaglet{
public HiddenTaglet() {
name = HIDDEN.tagName;
}
/**
* {@inheritDoc}
*/
public Content getTagletOutput(Element holder, TagletWriter writer) {
return writer.deprecatedTagOutput(holder);
}
}

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2015, 2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2015, 2018, 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
@ -25,11 +25,14 @@
package jdk.javadoc.internal.doclets.toolkit.taglets;
import com.sun.source.doctree.DocTree;
import java.util.Map;
import java.util.EnumSet;
import javax.lang.model.element.Element;
import com.sun.source.doctree.DocTree;
import jdk.javadoc.internal.doclets.toolkit.Content;
import static com.sun.source.doctree.DocTree.Kind.INDEX;
/**
* An inline Taglet used to index word or a phrase.
* The enclosed text is interpreted as not containing HTML markup or
@ -38,17 +41,13 @@ import jdk.javadoc.internal.doclets.toolkit.Content;
* @author Bhavesh Patel
*/
public class IndexTaglet extends BaseInlineTaglet {
public class IndexTaglet extends BaseTaglet {
private static final String NAME = "index";
public String getName() {
return NAME;
IndexTaglet() {
super(INDEX.tagName, true, EnumSet.allOf(Site.class));
}
/**
* {@inheritDoc}
*/
@Override
public Content getTagletOutput(Element element, DocTree tag, TagletWriter writer) {
return writer.indexTagOutput(element, tag);
}

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2017, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2018, 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
@ -25,6 +25,7 @@
package jdk.javadoc.internal.doclets.toolkit.taglets;
import java.util.EnumSet;
import javax.lang.model.element.Element;
import javax.lang.model.element.ExecutableElement;
@ -37,10 +38,10 @@ 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.*;
import static com.sun.source.doctree.DocTree.Kind.INHERIT_DOC;
/**
* An inline Taglet representing the <b>inheritDoc</b> tag. This tag should only
* An inline Taglet representing the {@code inheritDoc} tag. This tag should only
* be used with a method. It is used to inherit documentation from overriden
* and implemented methods.
*
@ -52,79 +53,19 @@ import static com.sun.source.doctree.DocTree.Kind.*;
* @author Jamie Ho
*/
public class InheritDocTaglet extends BaseInlineTaglet {
/**
* The inline tag that would appear in the documentation if
* the writer wanted documentation to be inherited.
*/
public static final String INHERIT_DOC_INLINE_TAG = "{@inheritDoc}";
public class InheritDocTaglet extends BaseTaglet {
/**
* Construct a new InheritDocTaglet.
*/
public InheritDocTaglet () {
name = INHERIT_DOC.tagName;
super(INHERIT_DOC.tagName, true, EnumSet.of(Site.TYPE, Site.METHOD));
}
/**
* Will return false because this inline tag may
* not appear in Fields.
* @return false
*/
public boolean inField() {
return false;
}
/**
* Will return false because this inline tag may
* not appear in Constructors.
* @return false
*/
public boolean inConstructor() {
return false;
}
/**
* Will return false because this inline tag may
* not appear in Overview.
* @return false
*/
public boolean inOverview() {
return false;
}
/**
* Will return false because this inline tag may
* not appear in Modules.
* @return false
*/
public boolean inModule() {
return false;
}
/**
* Will return false because this inline tag may
* not appear in Packages.
* @return false
*/
public boolean inPackage() {
return false;
}
/**
* Will return true because this inline tag may
* appear in Type (Class).
* @return true
*/
public boolean inType() {
return true;
}
/**
* Given a <code>MethodDoc</code> item, a <code>Tag</code> in the
* <code>MethodDoc</code> item and a String, replace all occurrences
* of @inheritDoc with documentation from it's superclass or superinterface.
* Given an element, a {@code DocTree} in the element's doc comment
* replace all occurrences of @inheritDoc with documentation from its
* superclass or superinterface.
*
* @param writer the writer that is writing the output.
* @param e the {@link Element} that we are documenting.
@ -148,7 +89,7 @@ public class InheritDocTaglet extends BaseInlineTaglet {
((utils.isExecutableElement(e))
? utils.flatSignature((ExecutableElement)e)
: "");
//This tag does not support inheritence.
//This tag does not support inheritance.
messages.warning(e, "doclet.noInheritedDoc", message);
}
Input input = new DocFinder.Input(utils, e,
@ -172,18 +113,9 @@ public class InheritDocTaglet extends BaseInlineTaglet {
return replacement;
}
/**
* Given the <code>Tag</code> representation of this custom
* tag, return its string representation, which is output
* to the generated page.
*
* @param e the element holding the tag
* @param tag the <code>Tag</code> representation of this custom tag.
* @param tagletWriter the taglet writer for output.
* @return the Content representation of this <code>Tag</code>.
*/
@Override
public Content getTagletOutput(Element e, DocTree tag, TagletWriter tagletWriter) {
DocTree inheritTag = tag.getKind() == INHERIT_DOC ? null : tag;
DocTree inheritTag = (tag.getKind() == INHERIT_DOC) ? null : tag;
return retrieveInheritedDocumentation(tagletWriter, e,
inheritTag, tagletWriter.isFirstSentence);
}

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2018, 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
@ -41,7 +41,7 @@ import jdk.javadoc.internal.doclets.toolkit.util.DocFinder;
public interface InheritableTaglet extends Taglet {
/**
* Given an {@link com.sun.tools.doclets.internal.toolkit.util.DocFinder.Output}
* Given an {@link jdk.javadoc.internal.doclets.toolkit.util.DocFinder.Output}
* object, set its values with the appropriate information to inherit
* documentation.
*

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2018, 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
@ -25,12 +25,13 @@
package jdk.javadoc.internal.doclets.toolkit.taglets;
import java.util.EnumSet;
import javax.lang.model.element.Element;
import com.sun.source.doctree.DocTree;
import jdk.javadoc.internal.doclets.toolkit.Content;
import static com.sun.source.doctree.DocTree.Kind.*;
import static com.sun.source.doctree.DocTree.Kind.LITERAL;
/**
* An inline Taglet used to denote literal text.
* For example, the text:
@ -46,17 +47,13 @@ import static com.sun.source.doctree.DocTree.Kind.*;
* @author Scott Seligman
*/
public class LiteralTaglet extends BaseInlineTaglet {
public class LiteralTaglet extends BaseTaglet {
private static final String NAME = LITERAL.tagName;
public String getName() {
return NAME;
LiteralTaglet() {
super(LITERAL.tagName, true, EnumSet.allOf(Site.class));
}
/**
* {@inheritDoc}
*/
@Override
public Content getTagletOutput(Element e, DocTree tag, TagletWriter writer) {
return writer.literalTagOutput(e, tag);
}

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2018, 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
@ -40,7 +40,7 @@ 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.*;
import static com.sun.source.doctree.DocTree.Kind.PARAM;
/**
* A taglet that represents the @param tag.
@ -58,7 +58,7 @@ public class ParamTaglet extends BaseTaglet implements InheritableTaglet {
* Construct a ParamTaglet.
*/
public ParamTaglet() {
name = PARAM.tagName;
super(PARAM.tagName, false, EnumSet.of(Site.TYPE, Site.CONSTRUCTOR, Site.METHOD));
}
/**
@ -85,9 +85,7 @@ public class ParamTaglet extends BaseTaglet implements InheritableTaglet {
return result;
}
/**
* {@inheritDoc}
*/
@Override
public void inherit(DocFinder.Input input, DocFinder.Output output) {
Utils utils = input.utils;
if (input.tagId == null) {
@ -129,61 +127,7 @@ public class ParamTaglet extends BaseTaglet implements InheritableTaglet {
}
}
/**
* {@inheritDoc}
*/
public boolean inField() {
return false;
}
/**
* {@inheritDoc}
*/
public boolean inMethod() {
return true;
}
/**
* {@inheritDoc}
*/
public boolean inOverview() {
return false;
}
/**
* {@inheritDoc}
*/
public boolean inModule() {
return false;
}
/**
* {@inheritDoc}
*/
public boolean inPackage() {
return false;
}
/**
* {@inheritDoc}
*/
public boolean inType() {
return true;
}
/**
* {@inheritDoc}
*/
public boolean isInlineTag() {
return false;
}
/**
* Given an array of <code>ParamTag</code>s,return its string representation.
* @param holder the member that holds the param tags.
* @param writer the TagletWriter that will write this tag.
* @return the TagletOutput representation of these <code>ParamTag</code>s.
*/
@Override
public Content getTagletOutput(Element holder, TagletWriter writer) {
Utils utils = writer.configuration().utils;
if (utils.isExecutableElement(holder)) {
@ -201,7 +145,7 @@ public class ParamTaglet extends BaseTaglet implements InheritableTaglet {
}
/**
* Given an array of <code>ParamTag</code>s,return its string representation.
* Given an array of {@code @param DocTree}s,return its string representation.
* Try to inherit the param tags that are missing.
*
* @param holder the element that holds the param tags.
@ -209,7 +153,7 @@ public class ParamTaglet extends BaseTaglet implements InheritableTaglet {
* @param formalParameters The array of parmeters (from type or executable
* member) to check.
*
* @return the TagletOutput representation of these <code>ParamTag</code>s.
* @return the content representation of these {@code @param DocTree}s.
*/
private Content getTagletOutput(boolean isParameters, Element holder,
TagletWriter writer, List<? extends Element> formalParameters, List<? extends DocTree> paramTags) {
@ -269,12 +213,12 @@ public class ParamTaglet extends BaseTaglet implements InheritableTaglet {
}
/**
* Given an array of <code>Tag</code>s representing this custom
* Given an array of {@code @param DocTree}s representing this
* tag, return its string representation. Print a warning for param
* tags that do not map to parameters. Print a warning for param
* tags that are duplicated.
*
* @param paramTags the array of <code>ParamTag</code>s to convert.
* @param paramTags the array of {@code @param DocTree} to convert.
* @param writer the TagletWriter that will write this tag.
* @param alreadyDocumented the set of exceptions that have already
* been documented.
@ -284,7 +228,7 @@ public class ParamTaglet extends BaseTaglet implements InheritableTaglet {
of a rank of a parameter to its name. This is
used to ensure that the right name is used
when parameter documentation is inherited.
* @return the Content representation of this <code>Tag</code>.
* @return the Content representation of this {@code @param DocTree}.
*/
private Content processParamTags(Element e, boolean isParams,
List<? extends DocTree> paramTags, Map<String, String> rankMap, TagletWriter writer,

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2015, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2018, 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
@ -47,7 +47,7 @@ public class PropertyGetterTaglet extends BasePropertyTaglet {
* Construct a new PropertyGetterTaglet.
*/
public PropertyGetterTaglet () {
name = "propertyGetter";
super("propertyGetter");
}
@Override

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2015, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2018, 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
@ -40,7 +40,7 @@ public class PropertySetterTaglet extends BasePropertyTaglet {
* Construct a new PropertyGetterTaglet.
*/
public PropertySetterTaglet () {
name = "propertySetter";
super("propertySetter");
}
@Override

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2018, 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
@ -26,6 +26,7 @@
package jdk.javadoc.internal.doclets.toolkit.taglets;
import java.util.ArrayList;
import java.util.EnumSet;
import java.util.List;
import javax.lang.model.element.Element;
@ -40,7 +41,7 @@ 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.*;
import static com.sun.source.doctree.DocTree.Kind.RETURN;
/**
* A taglet that represents the @return tag.
@ -52,15 +53,13 @@ import static com.sun.source.doctree.DocTree.Kind.*;
*
* @author Jamie Ho
*/
public class ReturnTaglet extends BaseExecutableMemberTaglet implements InheritableTaglet {
public class ReturnTaglet extends BaseTaglet implements InheritableTaglet {
public ReturnTaglet() {
name = RETURN.tagName;
super(RETURN.tagName, false, EnumSet.of(Site.METHOD));
}
/**
* {@inheritDoc}
*/
@Override
public void inherit(DocFinder.Input input, DocFinder.Output output) {
List<? extends DocTree> tags = input.utils.getBlockTags(input.element, DocTree.Kind.RETURN);
CommentHelper ch = input.utils.getCommentHelper(input.element);
@ -73,20 +72,7 @@ public class ReturnTaglet extends BaseExecutableMemberTaglet implements Inherita
}
}
/**
* Return true if this <code>Taglet</code>
* is used in constructor documentation.
* @return true if this <code>Taglet</code>
* is used in constructor documentation and false
* otherwise.
*/
public boolean inConstructor() {
return false;
}
/**
* {@inheritDoc}
*/
@Override
public Content getTagletOutput(Element holder, TagletWriter writer) {
Messages messages = writer.configuration().getMessages();
Utils utils = writer.configuration().utils;

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2018, 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
@ -25,6 +25,7 @@
package jdk.javadoc.internal.doclets.toolkit.taglets;
import java.util.EnumSet;
import java.util.List;
import javax.lang.model.element.Element;
@ -36,7 +37,7 @@ 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.*;
import static com.sun.source.doctree.DocTree.Kind.SEE;
/**
* A taglet that represents the @see tag.
@ -51,12 +52,10 @@ import static com.sun.source.doctree.DocTree.Kind.*;
public class SeeTaglet extends BaseTaglet implements InheritableTaglet {
public SeeTaglet() {
name = SEE.tagName;
super(SEE.tagName, false, EnumSet.allOf(Site.class));
}
/**
* {@inheritDoc}
*/
@Override
public void inherit(DocFinder.Input input, DocFinder.Output output) {
List<? extends DocTree> tags = input.utils.getSeeTrees(input.element);
if (!tags.isEmpty()) {
@ -69,9 +68,7 @@ public class SeeTaglet extends BaseTaglet implements InheritableTaglet {
}
}
/**
* {@inheritDoc}
*/
@Override
public Content getTagletOutput(Element holder, TagletWriter writer) {
Utils utils = writer.configuration().utils;
List<? extends DocTree> tags = utils.getSeeTrees(holder);

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2015, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2018, 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
@ -25,8 +25,9 @@
package jdk.javadoc.internal.doclets.toolkit.taglets;
import java.util.EnumSet;
import java.util.List;
import java.util.Locale;
import java.util.Set;
import javax.lang.model.element.Element;
@ -50,66 +51,18 @@ import jdk.javadoc.internal.doclets.toolkit.util.Utils;
public class SimpleTaglet extends BaseTaglet implements InheritableTaglet {
/**
* The marker in the location string for excluded tags.
*/
public static final String EXCLUDED = "x";
/**
* The marker in the location string for modules.
*/
public static final String MODULE = "s";
/**
* The marker in the location string for packages.
*/
public static final String PACKAGE = "p";
/**
* The marker in the location string for types.
*/
public static final String TYPE = "t";
/**
* The marker in the location string for constructors.
*/
public static final String CONSTRUCTOR = "c";
/**
* The marker in the location string for fields.
*/
public static final String FIELD = "f";
/**
* The marker in the location string for methods.
*/
public static final String METHOD = "m";
/**
* The marker in the location string for overview.
*/
public static final String OVERVIEW = "o";
/**
* Use in location string when the tag is to
* appear in all locations.
*/
public static final String ALL = "a";
/**
* The name of this tag.
*/
protected String tagName;
/**
* The header to output.
*/
protected String header;
/**
* The possible locations that this tag can appear in.
* Whether or not the taglet should generate output.
* Standard tags like at-author, at-since, at-version can be disabled
* by command-line options; custom tags created with -tag can be
* disabled with an X in the defining string.
*/
protected String locations;
protected final boolean enabled;
/**
* Construct a <code>SimpleTaglet</code>.
@ -121,113 +74,78 @@ public class SimpleTaglet extends BaseTaglet implements InheritableTaglet {
* and 'f' for field.
*/
public SimpleTaglet(String tagName, String header, String locations) {
this.tagName = tagName;
this(tagName, header, getSites(locations), isEnabled(locations));
}
/**
* Construct a <code>SimpleTaglet</code>.
* @param tagName the name of this tag
* @param header the header to output.
* @param sites the possible sites (locations) that this tag
* can appear in. The <code>String</code> can contain 'p'
* for package, 't' for type, 'm' for method, 'c' for constructor
* and 'f' for field.
*/
public SimpleTaglet(String tagName, String header, Set<Site> sites) {
this(tagName, header, sites, true);
}
/**
* Construct a <code>SimpleTaglet</code>.
* @param tagName the name of this tag
* @param header the header to output.
* @param sites the possible sites (locations) that this tag
* can appear in. The <code>String</code> can contain 'p'
* for package, 't' for type, 'm' for method, 'c' for constructor
* and 'f' for field.
*/
public SimpleTaglet(String tagName, String header, Set<Site> sites, boolean enabled) {
super(tagName, false, sites);
this.header = header;
locations = Utils.toLowerCase(locations);
if (locations.contains(ALL) && !locations.contains(EXCLUDED)) {
this.locations = MODULE + PACKAGE + TYPE + FIELD + METHOD + CONSTRUCTOR + OVERVIEW;
} else {
this.locations = locations;
this.enabled = enabled;
}
private static Set<Site> getSites(String locations) {
Set<Site> set = EnumSet.noneOf(Site.class);
for (int i = 0; i < locations.length(); i++) {
switch (locations.charAt(i)) {
case 'a': case 'A':
return EnumSet.allOf(Site.class);
case 'c': case 'C':
set.add(Site.CONSTRUCTOR);
break;
case 'f': case 'F':
set.add(Site.FIELD);
break;
case 'm': case 'M':
set.add(Site.METHOD);
break;
case 'o': case 'O':
set.add(Site.OVERVIEW);
break;
case 'p': case 'P':
set.add(Site.PACKAGE);
break;
case 's': case 'S': // super-packages, anyone?
set.add(Site.MODULE);
break;
case 't': case 'T':
set.add(Site.TYPE);
break;
case 'x': case 'X':
break;
}
}
return set;
}
/**
* Return the name of this <code>Taglet</code>.
*/
public String getName() {
return tagName;
}
/**
* Return true if this <code>SimpleTaglet</code>
* is used in constructor documentation.
* @return true if this <code>SimpleTaglet</code>
* is used in constructor documentation and false
* otherwise.
*/
public boolean inConstructor() {
return locations.contains(CONSTRUCTOR) && !locations.contains(EXCLUDED);
}
/**
* Return true if this <code>SimpleTaglet</code>
* is used in field documentation.
* @return true if this <code>SimpleTaglet</code>
* is used in field documentation and false
* otherwise.
*/
public boolean inField() {
return locations.contains(FIELD) && !locations.contains(EXCLUDED);
}
/**
* Return true if this <code>SimpleTaglet</code>
* is used in method documentation.
* @return true if this <code>SimpleTaglet</code>
* is used in method documentation and false
* otherwise.
*/
public boolean inMethod() {
return locations.contains(METHOD) && !locations.contains(EXCLUDED);
}
/**
* Return true if this <code>SimpleTaglet</code>
* is used in overview documentation.
* @return true if this <code>SimpleTaglet</code>
* is used in overview documentation and false
* otherwise.
*/
public boolean inOverview() {
return locations.contains(OVERVIEW) && !locations.contains(EXCLUDED);
}
/**
* Return true if this <code>SimpleTaglet</code>
* is used in module documentation.
* @return true if this <code>SimpleTaglet</code>
* is used in module documentation and false
* otherwise.
*/
public boolean inModule() {
return locations.contains(MODULE) && !locations.contains(EXCLUDED);
}
/**
* Return true if this <code>SimpleTaglet</code>
* is used in package documentation.
* @return true if this <code>SimpleTaglet</code>
* is used in package documentation and false
* otherwise.
*/
public boolean inPackage() {
return locations.contains(PACKAGE) && !locations.contains(EXCLUDED);
}
/**
* Return true if this <code>SimpleTaglet</code>
* is used in type documentation (classes or interfaces).
* @return true if this <code>SimpleTaglet</code>
* is used in type documentation and false
* otherwise.
*/
public boolean inType() {
return locations.contains(TYPE) && !locations.contains(EXCLUDED);
}
/**
* Return true if this <code>Taglet</code>
* is an inline tag.
* @return true if this <code>Taglet</code>
* is an inline tag and false otherwise.
*/
public boolean isInlineTag() {
return false;
private static boolean isEnabled(String locations) {
return locations.matches("[^Xx]*");
}
@Override
public void inherit(DocFinder.Input input, DocFinder.Output output) {
List<? extends DocTree> tags = input.utils.getBlockTags(input.element, tagName);
List<? extends DocTree> tags = input.utils.getBlockTags(input.element, name);
if (!tags.isEmpty()) {
output.holder = input.element;
output.holderTag = tags.get(0);
@ -238,16 +156,12 @@ public class SimpleTaglet extends BaseTaglet implements InheritableTaglet {
}
}
/**
* {@inheritDoc}
*/
@Override
public Content getTagletOutput(Element element, DocTree tag, TagletWriter writer) {
return header == null || tag == null ? null : writer.simpleTagOutput(element, tag, header);
}
/**
* {@inheritDoc}
*/
@Override
public Content getTagletOutput(Element holder, TagletWriter writer) {
Utils utils = writer.configuration().utils;
List<? extends DocTree> tags = utils.getBlockTags(holder, getName());

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2017, 2018, 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
@ -25,13 +25,14 @@
package jdk.javadoc.internal.doclets.toolkit.taglets;
import java.util.EnumSet;
import javax.lang.model.element.Element;
import com.sun.source.doctree.DocTree;
import com.sun.source.doctree.SummaryTree;
import jdk.javadoc.internal.doclets.toolkit.Content;
import static com.sun.source.doctree.DocTree.Kind.*;
import static com.sun.source.doctree.DocTree.Kind.SUMMARY;
/**
* A taglet that represents the @summary tag.
@ -42,15 +43,13 @@ import static com.sun.source.doctree.DocTree.Kind.*;
* deletion without notice.</b>
*/
public class SummaryTaglet extends BaseInlineTaglet {
public class SummaryTaglet extends BaseTaglet {
public SummaryTaglet() {
name = SUMMARY.tagName;
super(SUMMARY.tagName, true, EnumSet.allOf(Site.class));
}
/**
* {@inheritDoc}
*/
@Override
public Content getTagletOutput(Element holder, DocTree tag, TagletWriter writer) {
return writer.commentTagsToOutput(holder, ((SummaryTree)tag).getSummary());
}

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

@ -46,6 +46,7 @@ import jdk.javadoc.internal.doclets.toolkit.DocletElement;
import jdk.javadoc.internal.doclets.toolkit.Messages;
import jdk.javadoc.internal.doclets.toolkit.Resources;
import jdk.javadoc.internal.doclets.toolkit.taglets.BaseTaglet.Site;
import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
import jdk.javadoc.internal.doclets.toolkit.util.Utils;
@ -72,65 +73,29 @@ public class TagletManager {
public static final char SIMPLE_TAGLET_OPT_SEPARATOR = ':';
/**
* The alternate separator for simple tag options. Use this
* when you want the default separator to be in the name of the
* custom tag.
* The map of all taglets.
*/
public static final String ALT_SIMPLE_TAGLET_OPT_SEPARATOR = "-";
private final LinkedHashMap<String,Taglet> allTaglets;
/**
* The map of custom tags.
* Block (non-line) taglets, grouped by Site
*/
private final LinkedHashMap<String,Taglet> customTags;
private Map<Site, List<Taglet>> blockTagletsBySite;
/**
* The array of custom tags that can appear in modules.
*/
private List<Taglet> moduleTags;
/**
* The array of custom tags that can appear in packages.
*/
private List<Taglet> packageTags;
/**
* The array of custom tags that can appear in classes or interfaces.
*/
private List<Taglet> typeTags;
/**
* The array of custom tags that can appear in fields.
*/
private List<Taglet> fieldTags;
/**
* The array of custom tags that can appear in constructors.
*/
private List<Taglet> constructorTags;
/**
* The array of custom tags that can appear in methods.
*/
private List<Taglet> methodTags;
/**
* The array of custom tags that can appear in the overview.
*/
private List<Taglet> overviewTags;
/**
* The array of custom tags that can appear in comments.
* The taglets that can appear inline in descriptive text.
*/
private List<Taglet> inlineTags;
/**
* The array of custom tags that can appear in the serialized form.
* The taglets that can appear in the serialized form.
*/
private List<Taglet> serializedFormTags;
private final DocletEnvironment docEnv;
private final Doclet doclet;
private final Utils utils;
private final Messages messages;
private final Resources resources;
@ -184,7 +149,12 @@ public class TagletManager {
private final boolean javafx;
/**
* Construct a new <code>TagletManager</code>.
* Show the taglets table when it has been initialized.
*/
private final boolean showTaglets;
/**
* Construct a new {@code TagletManager}.
* @param nosince true if we do not want to use @since tags.
* @param showversion true if we want to use @version tags.
* @param showauthor true if we want to use @author tags.
@ -199,7 +169,7 @@ public class TagletManager {
standardTags = new HashSet<>();
standardTagsLowercase = new HashSet<>();
unseenCustomTags = new HashSet<>();
customTags = new LinkedHashMap<>();
allTaglets = new LinkedHashMap<>();
this.nosince = nosince;
this.showversion = showversion;
this.showauthor = showauthor;
@ -208,34 +178,33 @@ public class TagletManager {
this.doclet = configuration.doclet;
this.messages = configuration.getMessages();
this.resources = configuration.getResources();
this.showTaglets = configuration.showTaglets;
this.utils = configuration.utils;
initStandardTaglets();
initStandardTagsLowercase();
}
/**
* Add a new <code>CustomTag</code>. This is used to add a Taglet from within
* Add a new {@code Taglet}. This is used to add a Taglet from within
* a Doclet. No message is printed to indicate that the Taglet is properly
* registered because these Taglets are typically added for every execution of the
* Doclet. We don't want to see this type of error message every time.
* @param customTag the new <code>CustomTag</code> to add.
* @param customTag the new {@code Taglet} to add.
*/
public void addCustomTag(Taglet customTag) {
if (customTag != null) {
String name = customTag.getName();
if (customTags.containsKey(name)) {
customTags.remove(name);
}
customTags.put(name, customTag);
allTaglets.remove(name);
allTaglets.put(name, customTag);
checkTagName(name);
}
}
public Set<String> getCustomTagNames() {
return customTags.keySet();
public Set<String> getAllTagletNames() {
return allTaglets.keySet();
}
/**
* Add a new <code>Taglet</code>. Print a message to indicate whether or not
* Add a new {@code Taglet}. Print a message to indicate whether or not
* the Taglet was registered properly.
* @param classname the name of the class representing the custom tag.
* @param fileManager the filemanager to load classes and resources.
@ -262,11 +231,11 @@ public class TagletManager {
instance.init(docEnv, doclet);
Taglet newLegacy = new UserTaglet(instance);
String tname = newLegacy.getName();
Taglet t = customTags.get(tname);
Taglet t = allTaglets.get(tname);
if (t != null) {
customTags.remove(tname);
allTaglets.remove(tname);
}
customTags.put(tname, newLegacy);
allTaglets.put(tname, newLegacy);
messages.notice("doclet.Notice_taglet_registered", classname);
} catch (Exception exc) {
messages.error("doclet.Error_taglet_not_registered", exc.getClass().getName(), classname);
@ -274,7 +243,7 @@ public class TagletManager {
}
/**
* Add a new <code>SimpleTaglet</code>. If this tag already exists
* Add a new {@code SimpleTaglet}. If this tag already exists
* and the header passed as an argument is null, move tag to the back of the
* list. If this tag already exists and the header passed as an argument is
* not null, overwrite previous tag with new one. Otherwise, add new
@ -288,18 +257,17 @@ public class TagletManager {
if (tagName == null || locations == null) {
return;
}
Taglet tag = customTags.get(tagName);
locations = Utils.toLowerCase(locations);
Taglet tag = allTaglets.get(tagName);
if (tag == null || header != null) {
customTags.remove(tagName);
customTags.put(tagName, new SimpleTaglet(tagName, header, locations));
if (locations != null && locations.indexOf('x') == -1) {
allTaglets.remove(tagName);
allTaglets.put(tagName, new SimpleTaglet(tagName, header, locations));
if (Utils.toLowerCase(locations).indexOf('x') == -1) {
checkTagName(tagName);
}
} else {
//Move to back
customTags.remove(tagName);
customTags.put(tagName, tag);
allTaglets.remove(tagName);
allTaglets.put(tagName, tag);
}
}
@ -317,41 +285,22 @@ public class TagletManager {
}
}
/**
* Check the taglet to see if it is a legacy taglet. Also
* check its name for errors.
*/
private void checkTaglet(Object taglet) {
if (taglet instanceof Taglet) {
checkTagName(((Taglet) taglet).getName());
} else if (taglet instanceof jdk.javadoc.doclet.Taglet) {
jdk.javadoc.doclet.Taglet legacyTaglet = (jdk.javadoc.doclet.Taglet) taglet;
customTags.remove(legacyTaglet.getName());
customTags.put(legacyTaglet.getName(), new UserTaglet(legacyTaglet));
checkTagName(legacyTaglet.getName());
} else {
throw new IllegalArgumentException("Given object is not a taglet.");
}
}
/**
* Given a name of a seen custom tag, remove it from the set of unseen
* custom tags.
* @param name the name of the seen custom tag.
*/
public void seenCustomTag(String name) {
void seenCustomTag(String name) {
unseenCustomTags.remove(name);
}
/**
* Given an array of <code>Tag</code>s, check for spelling mistakes.
* @param utils the utility class to use
* Given a series of {@code DocTree}s, check for spelling mistakes.
* @param element the tags holder
* @param trees the trees containing the comments
* @param areInlineTags true if the array of tags are inline and false otherwise.
*/
public void checkTags(final Utils utils, Element element,
Iterable<? extends DocTree> trees, boolean areInlineTags) {
public void checkTags(Element element, Iterable<? extends DocTree> trees, boolean areInlineTags) {
if (trees == null) {
return;
}
@ -364,7 +313,7 @@ public class TagletManager {
if (name.length() > 0 && name.charAt(0) == '@') {
name = name.substring(1, name.length());
}
if (! (standardTags.contains(name) || customTags.containsKey(name))) {
if (! (standardTags.contains(name) || allTaglets.containsKey(name))) {
if (standardTagsLowercase.contains(Utils.toLowerCase(name))) {
messages.warning(ch.getDocTreePath(tag), "doclet.UnknownTagLowercase", ch.getTagName(tag));
continue;
@ -373,7 +322,7 @@ public class TagletManager {
continue;
}
}
final Taglet taglet = customTags.get(name);
final Taglet taglet = allTaglets.get(name);
// Check and verify tag usage
if (taglet != null) {
if (areInlineTags && !taglet.isInlineTag()) {
@ -452,6 +401,7 @@ public class TagletManager {
*/
private void printTagMisuseWarn(CommentHelper ch, Taglet taglet, DocTree tag, String holderType) {
Set<String> locationsSet = new LinkedHashSet<>();
// The following names should be localized
if (taglet.inOverview()) {
locationsSet.add("overview");
}
@ -476,230 +426,142 @@ public class TagletManager {
if (taglet.isInlineTag()) {
locationsSet.add("inline text");
}
String[] locations = locationsSet.toArray(new String[]{});
if (locations == null || locations.length == 0) {
if (locationsSet.isEmpty()) {
//This known tag is excluded.
return;
}
StringBuilder combined_locations = new StringBuilder();
for (int i = 0; i < locations.length; i++) {
if (i > 0) {
for (String location: locationsSet) {
if (combined_locations.length() > 0) {
combined_locations.append(", ");
}
combined_locations.append(locations[i]);
combined_locations.append(location);
}
messages.warning(ch.getDocTreePath(tag), "doclet.tag_misuse",
"@" + taglet.getName(), holderType, combined_locations.toString());
}
/**
* Return the array of <code>Taglet</code>s that can
* appear in modules.
* @return the array of <code>Taglet</code>s that can
* appear in modules.
* Returns the taglets that can appear inline, in descriptive text.
* @return the taglets that can appear inline
*/
public List<Taglet> getModuleCustomTaglets() {
if (moduleTags == null) {
initCustomTaglets();
}
return moduleTags;
}
/**
* Return the array of <code>Taglet</code>s that can
* appear in packages.
* @return the array of <code>Taglet</code>s that can
* appear in packages.
*/
public List<Taglet> getPackageCustomTaglets() {
if (packageTags == null) {
initCustomTaglets();
}
return packageTags;
}
/**
* Return the array of <code>Taglet</code>s that can
* appear in classes or interfaces.
* @return the array of <code>Taglet</code>s that can
* appear in classes or interfaces.
*/
public List<Taglet> getTypeCustomTaglets() {
if (typeTags == null) {
initCustomTaglets();
}
return typeTags;
}
/**
* Return the array of inline <code>Taglet</code>s that can
* appear in comments.
* @return the array of <code>Taglet</code>s that can
* appear in comments.
*/
public List<Taglet> getInlineCustomTaglets() {
List<Taglet> getInlineTaglets() {
if (inlineTags == null) {
initCustomTaglets();
initBlockTaglets();
}
return inlineTags;
}
/**
* Return the array of <code>Taglet</code>s that can
* appear in fields.
* @return the array of <code>Taglet</code>s that can
* appear in field.
*/
public List<Taglet> getFieldCustomTaglets() {
if (fieldTags == null) {
initCustomTaglets();
}
return fieldTags;
}
/**
* Return the array of <code>Taglet</code>s that can
* appear in the serialized form.
* @return the array of <code>Taglet</code>s that can
* appear in the serialized form.
* Returns the taglets that can appear in the serialized form.
* @return the taglet that can appear in the serialized form
*/
public List<Taglet> getSerializedFormTaglets() {
if (serializedFormTags == null) {
initCustomTaglets();
initBlockTaglets();
}
return serializedFormTags;
}
@SuppressWarnings("fallthrough")
/**
* Returns the custom tags for a given element.
*
* @param e the element to get custom tags for
* @return the array of <code>Taglet</code>s that can
* @return the array of {@code Taglet}s that can
* appear in the given element.
*/
public List<Taglet> getCustomTaglets(Element e) {
@SuppressWarnings("fallthrough")
public List<Taglet> getBlockTaglets(Element e) {
if (blockTagletsBySite == null) {
initBlockTaglets();
}
switch (e.getKind()) {
case CONSTRUCTOR:
return getConstructorCustomTaglets();
return blockTagletsBySite.get(Site.CONSTRUCTOR);
case METHOD:
return getMethodCustomTaglets();
return blockTagletsBySite.get(Site.METHOD);
case ENUM_CONSTANT:
case FIELD:
return getFieldCustomTaglets();
return blockTagletsBySite.get(Site.FIELD);
case ANNOTATION_TYPE:
case INTERFACE:
case CLASS:
case ENUM:
return getTypeCustomTaglets();
return blockTagletsBySite.get(Site.TYPE);
case MODULE:
return getModuleCustomTaglets();
return blockTagletsBySite.get(Site.MODULE);
case PACKAGE:
return getPackageCustomTaglets();
return blockTagletsBySite.get(Site.PACKAGE);
case OTHER:
if (e instanceof DocletElement) {
DocletElement de = (DocletElement)e;
switch (de.getSubKind()) {
case DOCFILE:
return getPackageCustomTaglets();
return blockTagletsBySite.get(Site.PACKAGE);
case OVERVIEW:
return getOverviewCustomTaglets();
return blockTagletsBySite.get(Site.OVERVIEW);
default:
// fall through
}
}
// fall through
default:
throw new AssertionError("unknown element: " + e + " ,kind: " + e.getKind());
}
}
/**
* Return a List of <code>Taglet</code>s that can
* appear in constructors.
* @return the array of <code>Taglet</code>s that can
* appear in constructors.
*/
public List<Taglet> getConstructorCustomTaglets() {
if (constructorTags == null) {
initCustomTaglets();
}
return constructorTags;
}
/**
* Return a List of <code>Taglet</code>s that can
* appear in methods.
* @return the array of <code>Taglet</code>s that can
* appear in methods.
*/
public List<Taglet> getMethodCustomTaglets() {
if (methodTags == null) {
initCustomTaglets();
}
return methodTags;
}
/**
* Return a List of <code>Taglet</code>s that can
* appear in an overview.
* @return the array of <code>Taglet</code>s that can
* appear in overview.
*/
public List<Taglet> getOverviewCustomTaglets() {
if (overviewTags == null) {
initCustomTaglets();
}
return overviewTags;
}
/**
* Initialize the custom tag Lists.
*/
private void initCustomTaglets() {
private void initBlockTaglets() {
blockTagletsBySite = new EnumMap<>(Site.class);
for (Site site : Site.values()) {
blockTagletsBySite.put(site, new ArrayList<>());
}
moduleTags = new ArrayList<>();
packageTags = new ArrayList<>();
typeTags = new ArrayList<>();
fieldTags = new ArrayList<>();
constructorTags = new ArrayList<>();
methodTags = new ArrayList<>();
inlineTags = new ArrayList<>();
overviewTags = new ArrayList<>();
for (Taglet current : customTags.values()) {
if (current.inModule() && !current.isInlineTag()) {
moduleTags.add(current);
}
if (current.inPackage() && !current.isInlineTag()) {
packageTags.add(current);
}
if (current.inType() && !current.isInlineTag()) {
typeTags.add(current);
}
if (current.inField() && !current.isInlineTag()) {
fieldTags.add(current);
}
if (current.inConstructor() && !current.isInlineTag()) {
constructorTags.add(current);
}
if (current.inMethod() && !current.isInlineTag()) {
methodTags.add(current);
}
for (Taglet current : allTaglets.values()) {
if (current.isInlineTag()) {
inlineTags.add(current);
}
if (current.inOverview() && !current.isInlineTag()) {
overviewTags.add(current);
} else {
if (current.inOverview()) {
blockTagletsBySite.get(Site.OVERVIEW).add(current);
}
if (current.inModule()) {
blockTagletsBySite.get(Site.MODULE).add(current);
}
if (current.inPackage()) {
blockTagletsBySite.get(Site.PACKAGE).add(current);
}
if (current.inType()) {
blockTagletsBySite.get(Site.TYPE).add(current);
}
if (current.inConstructor()) {
blockTagletsBySite.get(Site.CONSTRUCTOR).add(current);
}
if (current.inMethod()) {
blockTagletsBySite.get(Site.METHOD).add(current);
}
if (current.inField()) {
blockTagletsBySite.get(Site.FIELD).add(current);
}
}
}
//Init the serialized form tags
serializedFormTags = new ArrayList<>();
serializedFormTags.add(customTags.get(SERIAL_DATA.tagName));
serializedFormTags.add(customTags.get(THROWS.tagName));
serializedFormTags.add(allTaglets.get(SERIAL_DATA.tagName));
serializedFormTags.add(allTaglets.get(THROWS.tagName));
if (!nosince)
serializedFormTags.add(customTags.get(SINCE.tagName));
serializedFormTags.add(customTags.get(SEE.tagName));
serializedFormTags.add(allTaglets.get(SINCE.tagName));
serializedFormTags.add(allTaglets.get(SEE.tagName));
if (showTaglets) {
showTaglets(System.out);
}
}
/**
@ -710,26 +572,36 @@ public class TagletManager {
initJavaFXTaglets();
}
Taglet temp;
addStandardTaglet(new ParamTaglet());
addStandardTaglet(new ReturnTaglet());
addStandardTaglet(new ThrowsTaglet());
addStandardTaglet(new SimpleTaglet(EXCEPTION.tagName, null,
SimpleTaglet.METHOD + SimpleTaglet.CONSTRUCTOR));
addStandardTaglet(!nosince, new SimpleTaglet(SINCE.tagName, resources.getText("doclet.Since"),
SimpleTaglet.ALL));
addStandardTaglet(showversion, new SimpleTaglet(VERSION.tagName, resources.getText("doclet.Version"),
SimpleTaglet.MODULE + SimpleTaglet.PACKAGE + SimpleTaglet.TYPE + SimpleTaglet.OVERVIEW));
addStandardTaglet(showauthor, new SimpleTaglet(AUTHOR.tagName, resources.getText("doclet.Author"),
SimpleTaglet.MODULE + SimpleTaglet.PACKAGE + SimpleTaglet.TYPE + SimpleTaglet.OVERVIEW));
addStandardTaglet(new SimpleTaglet(SERIAL_DATA.tagName, resources.getText("doclet.SerialData"),
SimpleTaglet.EXCLUDED));
addStandardTaglet(new SimpleTaglet(HIDDEN.tagName, resources.getText("doclet.Hidden"),
SimpleTaglet.FIELD + SimpleTaglet.METHOD + SimpleTaglet.TYPE));
customTags.put((temp = new SimpleTaglet("factory", resources.getText("doclet.Factory"),
SimpleTaglet.METHOD)).getName(), temp);
addStandardTaglet(
new SimpleTaglet(EXCEPTION.tagName, null,
EnumSet.of(Site.METHOD, Site.CONSTRUCTOR)));
addStandardTaglet(
new SimpleTaglet(SINCE.tagName, resources.getText("doclet.Since"),
EnumSet.allOf(Site.class), !nosince));
addStandardTaglet(
new SimpleTaglet(VERSION.tagName, resources.getText("doclet.Version"),
EnumSet.of(Site.OVERVIEW, Site.MODULE, Site.PACKAGE, Site.TYPE), showversion));
addStandardTaglet(
new SimpleTaglet(AUTHOR.tagName, resources.getText("doclet.Author"),
EnumSet.of(Site.OVERVIEW, Site.MODULE, Site.PACKAGE, Site.TYPE), showauthor));
addStandardTaglet(
new SimpleTaglet(SERIAL_DATA.tagName, resources.getText("doclet.SerialData"),
EnumSet.noneOf(Site.class)));
addStandardTaglet(
new SimpleTaglet(HIDDEN.tagName, null,
EnumSet.of(Site.TYPE, Site.METHOD, Site.FIELD)));
// This appears to be a default custom (non-standard) taglet
Taglet factoryTaglet = new SimpleTaglet("factory", resources.getText("doclet.Factory"),
EnumSet.of(Site.METHOD));
allTaglets.put(factoryTaglet.getName(), factoryTaglet);
addStandardTaglet(new SeeTaglet());
//Standard inline tags
// Standard inline tags
addStandardTaglet(new DocRootTaglet());
addStandardTaglet(new InheritDocTaglet());
addStandardTaglet(new ValueTaglet());
@ -738,13 +610,18 @@ public class TagletManager {
addStandardTaglet(new IndexTaglet());
addStandardTaglet(new SummaryTaglet());
// Keep track of the names of standard tags for error
// checking purposes. The following are not handled above.
standardTags.add(DEPRECATED.tagName);
standardTags.add(LINK.tagName);
standardTags.add(LINK_PLAIN.tagName);
standardTags.add(SERIAL.tagName);
standardTags.add(SERIAL_FIELD.tagName);
// Keep track of the names of standard tags for error checking purposes.
// The following are not handled above.
addStandardTaglet(new DeprecatedTaglet());
addStandardTaglet(new BaseTaglet(LINK.tagName, true, EnumSet.allOf(Site.class)));
addStandardTaglet(new BaseTaglet(LINK_PLAIN.tagName, true, EnumSet.allOf(Site.class)));
addStandardTaglet(new BaseTaglet(USES.tagName, false, EnumSet.of(Site.MODULE)));
addStandardTaglet(new BaseTaglet(PROVIDES.tagName, false, EnumSet.of(Site.MODULE)));
addStandardTaglet(
new SimpleTaglet(SERIAL.tagName, null,
EnumSet.of(Site.PACKAGE, Site.TYPE, Site.FIELD)));
addStandardTaglet(
new SimpleTaglet(SERIAL_FIELD.tagName, null, EnumSet.of(Site.FIELD)));
}
/**
@ -755,37 +632,22 @@ public class TagletManager {
addStandardTaglet(new PropertySetterTaglet());
addStandardTaglet(new SimpleTaglet("propertyDescription",
resources.getText("doclet.PropertyDescription"),
SimpleTaglet.FIELD + SimpleTaglet.METHOD));
EnumSet.of(Site.METHOD, Site.FIELD)));
addStandardTaglet(new SimpleTaglet("defaultValue", resources.getText("doclet.DefaultValue"),
SimpleTaglet.FIELD + SimpleTaglet.METHOD));
EnumSet.of(Site.METHOD, Site.FIELD)));
addStandardTaglet(new SimpleTaglet("treatAsPrivate", null,
SimpleTaglet.FIELD + SimpleTaglet.METHOD + SimpleTaglet.TYPE));
EnumSet.of(Site.TYPE, Site.METHOD, Site.FIELD)));
}
void addStandardTaglet(Taglet taglet) {
private void addStandardTaglet(Taglet taglet) {
String name = taglet.getName();
customTags.put(name, taglet);
allTaglets.put(name, taglet);
standardTags.add(name);
}
void addStandardTaglet(boolean enable, Taglet taglet) {
String name = taglet.getName();
if (enable)
customTags.put(name, taglet);
standardTags.add(name);
}
/**
* Initialize lowercase version of standard Javadoc tags.
*/
private void initStandardTagsLowercase() {
for (String standardTag : standardTags) {
standardTagsLowercase.add(Utils.toLowerCase(standardTag));
}
standardTagsLowercase.add(Utils.toLowerCase(name));
}
public boolean isKnownCustomTag(String tagName) {
return customTags.containsKey(tagName);
return allTaglets.containsKey(tagName);
}
/**
@ -801,13 +663,10 @@ public class TagletManager {
private void printReportHelper(String noticeKey, Set<String> names) {
if (names.size() > 0) {
String[] namesArray = names.toArray(new String[] {});
String result = " ";
for (int i = 0; i < namesArray.length; i++) {
result += "@" + namesArray[i];
if (i + 1 < namesArray.length) {
result += ", ";
}
StringBuilder result = new StringBuilder();
for (String name : names) {
result.append(result.length() == 0 ? " " : ", ");
result.append("@").append(name);
}
messages.notice(noticeKey, result);
}
@ -821,12 +680,40 @@ public class TagletManager {
* @return return the corresponding taglet. Return null if the tag is
* unknown.
*/
public Taglet getTaglet(String name) {
Taglet getTaglet(String name) {
if (name.indexOf("@") == 0) {
return customTags.get(name.substring(1));
return allTaglets.get(name.substring(1));
} else {
return customTags.get(name);
return allTaglets.get(name);
}
}
/*
* The output of this method is the basis for a table at the end of the
* doc comment specification, so any changes in the output may indicate
* a need for a corresponding update to the spec.
*/
private void showTaglets(PrintStream out) {
Set<Taglet> taglets = new TreeSet<>((o1, o2) -> o1.getName().compareTo(o2.getName()));
taglets.addAll(allTaglets.values());
for (Taglet t : taglets) {
String name = t.isInlineTag() ? "{@" + t.getName() + "}" : "@" + t.getName();
out.println(String.format("%20s", name) + ": "
+ format(t.inOverview(), "overview") + " "
+ format(t.inModule(), "module") + " "
+ format(t.inPackage(), "package") + " "
+ format(t.inType(), "type") + " "
+ format(t.inConstructor(),"constructor") + " "
+ format(t.inMethod(), "method") + " "
+ format(t.inField(), "field") + " "
+ format(t.isInlineTag(), "inline")+ " "
+ format((t instanceof SimpleTaglet) && !((SimpleTaglet)t).enabled, "disabled"));
}
}
private String format(boolean b, String s) {
return b ? s : s.replaceAll(".", "."); // replace all with "."
}
}

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2018, 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
@ -220,8 +220,8 @@ public abstract class TagletWriter {
public static void genTagOutput(TagletManager tagletManager, Element element,
List<Taglet> taglets, TagletWriter writer, Content output) {
Utils utils = writer.configuration().utils;
tagletManager.checkTags(utils, element, utils.getBlockTags(element), false);
tagletManager.checkTags(utils, element, utils.getFullBody(element), true);
tagletManager.checkTags(element, utils.getBlockTags(element), false);
tagletManager.checkTags(element, utils.getFullBody(element), true);
for (Taglet taglet : taglets) {
if (utils.isTypeElement(element) && taglet instanceof ParamTaglet) {
//The type parameters are documented in a special section away
@ -233,6 +233,10 @@ public abstract class TagletWriter {
//section.
continue;
}
if (taglet instanceof SimpleTaglet && !((SimpleTaglet) taglet).enabled) {
// taglet has been disabled
continue;
}
Content currentOutput = null;
try {
currentOutput = taglet.getTagletOutput(element, writer);
@ -262,7 +266,7 @@ public abstract class TagletWriter {
*/
public static Content getInlineTagOutput(Element holder, TagletManager tagletManager,
DocTree holderTag, DocTree inlineTag, TagletWriter tagletWriter) {
List<Taglet> definedTags = tagletManager.getInlineCustomTaglets();
List<Taglet> definedTags = tagletManager.getInlineTaglets();
CommentHelper ch = tagletWriter.configuration().utils.getCommentHelper(holder);
final String inlineTagName = ch.getTagName(inlineTag);
//This is a custom inline tag.

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2018, 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
@ -40,7 +40,7 @@ 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.*;
import static com.sun.source.doctree.DocTree.Kind.THROWS;
/**
* A taglet that represents the @throws tag.
@ -52,16 +52,13 @@ import static com.sun.source.doctree.DocTree.Kind.*;
*
* @author Jamie Ho
*/
public class ThrowsTaglet extends BaseExecutableMemberTaglet
public class ThrowsTaglet extends BaseTaglet
implements InheritableTaglet {
public ThrowsTaglet() {
name = THROWS.tagName;
super(THROWS.tagName, false, EnumSet.of(Site.CONSTRUCTOR, Site.METHOD));
}
/**
* {@inheritDoc}
*/
@Override
public void inherit(DocFinder.Input input, DocFinder.Output output) {
Utils utils = input.utils;

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2017, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2018, 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
@ -25,6 +25,7 @@
package jdk.javadoc.internal.doclets.toolkit.taglets;
import java.util.EnumSet;
import javax.lang.model.element.Element;
import javax.lang.model.element.VariableElement;
@ -35,7 +36,7 @@ import jdk.javadoc.internal.doclets.toolkit.Messages;
import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
import jdk.javadoc.internal.doclets.toolkit.util.Utils;
import static com.sun.source.doctree.DocTree.Kind.*;
import static com.sun.source.doctree.DocTree.Kind.VALUE;
/**
* An inline Taglet representing the value tag. This tag should only be used with
@ -54,67 +55,15 @@ import static com.sun.source.doctree.DocTree.Kind.*;
* @author Jamie Ho
*/
public class ValueTaglet extends BaseInlineTaglet {
public class ValueTaglet extends BaseTaglet {
/**
* Construct a new ValueTaglet.
*/
public ValueTaglet() {
name = VALUE.tagName;
}
/**
* Will return false because this inline tag may
* only appear in Fields.
* @return false since this is not a method.
*/
public boolean inMethod() {
return true;
}
/**
* Will return false because this inline tag may
* only appear in Fields.
* @return false since this is not a method.
*/
public boolean inConstructor() {
return true;
}
/**
* Will return false because this inline tag may
* only appear in Fields.
* @return false since this is not a method.
*/
public boolean inOverview() {
return true;
}
/**
* Will return false because this inline tag may
* only appear in Fields.
* @return false since this is not a field.
*/
public boolean inModule() {
return false;
}
/**
* Will return false because this inline tag may
* only appear in Fields.
* @return false since this is not a method.
*/
public boolean inPackage() {
return true;
}
/**
* Will return false because this inline tag may
* only appear in Fields.
* @return false since this is not a method.
*/
public boolean inType() {
return true;
super(VALUE.tagName, true,
EnumSet.of(Site.OVERVIEW, Site.PACKAGE, Site.TYPE, Site.CONSTRUCTOR,
Site.METHOD, Site.FIELD)); // not Site.MODULE at this time!
}
/**
@ -140,9 +89,7 @@ public class ValueTaglet extends BaseInlineTaglet {
: null;
}
/**
* {@inheritDoc}
*/
@Override
public Content getTagletOutput(Element holder, DocTree tag, TagletWriter writer) {
Utils utils = writer.configuration().utils;
Messages messages = writer.configuration().getMessages();

88
test/langtools/jdk/javadoc/doclet/testAuthor/TestAuthor.java Normal file

@ -0,0 +1,88 @@
/*
* Copyright (c) 2018, 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/*
* @test
* @bug 8202947
* @summary test the at-author tag, and corresponding option
* @library /tools/lib ../lib
* @modules jdk.javadoc/jdk.javadoc.internal.tool
* @build toolbox.ToolBox JavadocTester
* @run main TestAuthor
*/
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import toolbox.ToolBox;
public class TestAuthor extends JavadocTester {
public static void main(String... args) throws Exception {
TestAuthor tester = new TestAuthor();
tester.runTests();
}
ToolBox tb = new ToolBox();
Path src;
TestAuthor() throws Exception {
src = Files.createDirectories(Paths.get("src"));
tb.writeJavaFiles(src,
"package pkg;\n"
+ "/** Introduction. \n"
+ " * @author anonymous\n"
+ " */\n"
+ "public class Test { }\n");
}
@Test
void testAuthor() {
javadoc("-d", "out-author",
"-sourcepath", src.toString(),
"-author",
"pkg");
checkExit(Exit.OK);
checkAuthor(true);
}
@Test
void testNoAuthor() {
javadoc("-d", "out-noauthor",
"-sourcepath", src.toString(),
"pkg");
checkExit(Exit.OK);
checkAuthor(false);
}
void checkAuthor(boolean on) {
checkOutput("pkg/Test.html", on,
"<dl>\n"
+ "<dt><span class=\"simpleTagLabel\">Author:</span></dt>\n"
+ "<dd>anonymous</dd>\n"
+ "</dl>");
}
}

82
test/langtools/jdk/javadoc/doclet/testTaglets/TestTaglets.java Normal file

@ -0,0 +1,82 @@
/*
* Copyright (c) 2018, 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/*
* @test
* @bug 8202947
* @summary Test TagletManager initialization
* @library /tools/lib ../lib
* @modules jdk.javadoc/jdk.javadoc.internal.tool
* @build toolbox.ToolBox JavadocTester
* @run main TestTaglets
*/
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.List;
import toolbox.ToolBox;
/*
* This is a golden-file test for the output of the hidden
* option {@code --show-taglets}. The output is the basis
* for a table at the end of the doc comment specification,
* so changes in the golden output may indicate a need for
* a corresponding update to the spec.
*/
public class TestTaglets extends JavadocTester {
public static void main(String... args) throws Exception {
TestTaglets tester = new TestTaglets();
tester.runTests();
}
ToolBox tb = new ToolBox();
Path src;
TestTaglets() throws Exception {
src = Files.createDirectories(Paths.get("src"));
tb.writeJavaFiles(src, "public class Test { }\n");
}
@Test
void test() throws Exception {
javadoc("-d", "out",
"-javafx",
"--show-taglets",
src.resolve("Test.java").toString());
checkExit(Exit.OK);
checking("Checking ref file");
try {
List<String> refLines = tb.readAllLines(Paths.get(testSrc).resolve("TestTaglets.out"));
List<String> stdout = getOutputLines(Output.STDOUT);
tb.checkEqual(refLines, stdout);
passed("output is as expected");
} catch (Error e) {
failed("output not as expected: " + e.getMessage());
}
}
}

30
test/langtools/jdk/javadoc/doclet/testTaglets/TestTaglets.out Normal file

@ -0,0 +1,30 @@
@author: overview module package type ........... ...... ..... ...... disabled
{@code}: overview module package type constructor method field inline ........
@defaultValue: ........ ...... ....... .... ........... method field ...... ........
@deprecated: ........ module ....... type constructor method field ...... ........
{@docRoot}: overview module package type constructor method field inline ........
@exception: ........ ...... ....... .... constructor method ..... ...... ........
@factory: ........ ...... ....... .... ........... method ..... ...... ........
@hidden: ........ ...... ....... type ........... method field ...... ........
{@index}: overview module package type constructor method field inline ........
{@inheritDoc}: ........ ...... ....... type ........... method ..... inline ........
{@link}: overview module package type constructor method field inline ........
{@linkplain}: overview module package type constructor method field inline ........
{@literal}: overview module package type constructor method field inline ........
@param: ........ ...... ....... type constructor method ..... ...... ........
@propertyDescription: ........ ...... ....... .... ........... method field ...... ........
@propertyGetter: ........ ...... ....... .... ........... method ..... ...... ........
@propertySetter: ........ ...... ....... .... ........... method ..... ...... ........
@provides: ........ module ....... .... ........... ...... ..... ...... ........
@return: ........ ...... ....... .... ........... method ..... ...... ........
@see: overview module package type constructor method field ...... ........
@serial: ........ ...... package type ........... ...... field ...... ........
@serialData: ........ ...... ....... .... ........... ...... ..... ...... ........
@serialField: ........ ...... ....... .... ........... ...... field ...... ........
@since: overview module package type constructor method field ...... ........
{@summary}: overview module package type constructor method field inline ........
@throws: ........ ...... ....... .... constructor method ..... ...... ........
@treatAsPrivate: ........ ...... ....... type ........... method field ...... ........
@uses: ........ module ....... .... ........... ...... ..... ...... ........
{@value}: overview ...... package type constructor method field inline ........
@version: overview module package type ........... ...... ..... ...... disabled

88
test/langtools/jdk/javadoc/doclet/testVersionTag/TestVersionTag.java Normal file

@ -0,0 +1,88 @@
/*
* Copyright (c) 2018, 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/*
* @test
* @bug 8202947
* @summary test the at-version tag, and corresponding option
* @library /tools/lib ../lib
* @modules jdk.javadoc/jdk.javadoc.internal.tool
* @build toolbox.ToolBox JavadocTester
* @run main TestVersionTag
*/
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import toolbox.ToolBox;
public class TestVersionTag extends JavadocTester {
public static void main(String... args) throws Exception {
TestVersionTag tester = new TestVersionTag();
tester.runTests();
}
ToolBox tb = new ToolBox();
Path src;
TestVersionTag() throws Exception {
src = Files.createDirectories(Paths.get("src"));
tb.writeJavaFiles(src,
"package pkg;\n"
+ "/** Introduction. \n"
+ " * @version 1.2.3\n"
+ " */\n"
+ "public class Test { }\n");
}
@Test
void testVersion() {
javadoc("-d", "out-version",
"-sourcepath", src.toString(),
"-version",
"pkg");
checkExit(Exit.OK);
checkVersion(true);
}
@Test
void testNoVersion() {
javadoc("-d", "out-noversion",
"-sourcepath", src.toString(),
"pkg");
checkExit(Exit.OK);
checkVersion(false);
}
void checkVersion(boolean on) {
checkOutput("pkg/Test.html", on,
"<dl>\n"
+ "<dt><span class=\"simpleTagLabel\">Version:</span></dt>\n"
+ "<dd>1.2.3</dd>\n"
+ "</dl>");
}
}

3
test/langtools/jdk/javadoc/tool/CheckResourceKeys.java

@ -168,6 +168,9 @@ public class CheckResourceKeys {
// ignore this partial key, tested by usageTests
if (ck.equals("main.opt."))
continue;
// ignore this system property name
if (ck.equals("javadoc.internal.show.taglets"))
continue;
if (resourceKeys.contains(ck))
continue;
error("No resource for \"" + ck + "\"");

4
test/langtools/tools/lib/toolbox/ToolBox.java

@ -1,5 +1,5 @@
/*
* Copyright (c) 2013, 2017, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2013, 2018, 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
@ -142,7 +142,7 @@ public class ToolBox {
// report first difference
for (int i = 0; i < Math.min(l1.size(), l2.size()); i++) {
String s1 = l1.get(i);
String s2 = l1.get(i);
String s2 = l2.get(i);
if (!Objects.equals(s1, s2)) {
throw new Error("comparison failed, index " + i +
", (" + s1 + ":" + s2 + ")");