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

feat(jdk8): move files to new folder to avoid resources compiled.

Browse Source
This commit is contained in:
linkerlau
2025-09-07 15:25:52 +08:00
parent 3f0047bf6f
commit 8c35cfb1c0
17415 changed files with 217 additions and 213 deletions
Download Patch File Download Diff File Expand all files Collapse all files

211
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/AbstractDoclet.java Normal file
View File

@@ -0,0 +1,211 @@
/*
* Copyright (c) 2003, 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 com.sun.tools.doclets.internal.toolkit;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.builders.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* An abstract implementation of a Doclet.
*
* <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 AbstractDoclet {
/**
* The global configuration information for this run.
*/
public Configuration configuration;
/**
* The only doclet that may use this toolkit is {@value}
*/
private static final String TOOLKIT_DOCLET_NAME =
com.sun.tools.doclets.formats.html.HtmlDoclet.class.getName();
/**
* Verify that the only doclet that is using this toolkit is
* {@value #TOOLKIT_DOCLET_NAME}.
*/
private boolean isValidDoclet(AbstractDoclet doclet) {
if (! doclet.getClass().getName().equals(TOOLKIT_DOCLET_NAME)) {
configuration.message.error("doclet.Toolkit_Usage_Violation",
TOOLKIT_DOCLET_NAME);
return false;
}
return true;
}
/**
* The method that starts the execution of the doclet.
*
* @param doclet the doclet to start the execution for.
* @param root the {@link RootDoc} that points to the source to document.
* @return true if the doclet executed without error. False otherwise.
*/
public boolean start(AbstractDoclet doclet, RootDoc root) {
configuration = configuration();
configuration.root = root;
if (! isValidDoclet(doclet)) {
return false;
}
try {
doclet.startGeneration(root);
} catch (Configuration.Fault f) {
root.printError(f.getMessage());
return false;
} catch (FatalError fe) {
return false;
} catch (DocletAbortException e) {
Throwable cause = e.getCause();
if (cause != null) {
if (cause.getLocalizedMessage() != null) {
root.printError(cause.getLocalizedMessage());
} else {
root.printError(cause.toString());
}
}
return false;
} catch (Exception exc) {
exc.printStackTrace();
return false;
}
return true;
}
/**
* Indicate that this doclet supports the 1.5 language features.
* @return JAVA_1_5, indicating that the new features are supported.
*/
public static LanguageVersion languageVersion() {
return LanguageVersion.JAVA_1_5;
}
/**
* Create the configuration instance and returns it.
* @return the configuration of the doclet.
*/
public abstract Configuration configuration();
/**
* Start the generation of files. Call generate methods in the individual
* writers, which will in turn generate the documentation files. Call the
* TreeWriter generation first to ensure the Class Hierarchy is built
* first and then can be used in the later generation.
*
* @see com.sun.javadoc.RootDoc
*/
private void startGeneration(RootDoc root) throws Configuration.Fault, Exception {
if (root.classes().length == 0) {
configuration.message.
error("doclet.No_Public_Classes_To_Document");
return;
}
configuration.setOptions();
configuration.getDocletSpecificMsg().notice("doclet.build_version",
configuration.getDocletSpecificBuildDate());
ClassTree classtree = new ClassTree(configuration, configuration.nodeprecated);
generateClassFiles(root, classtree);
Util.copyDocFiles(configuration, DocPaths.DOC_FILES);
PackageListWriter.generate(configuration);
generatePackageFiles(classtree);
generateProfileFiles();
generateOtherFiles(root, classtree);
configuration.tagletManager.printReport();
}
/**
* Generate additional documentation that is added to the API documentation.
*
* @param root the RootDoc of source to document.
* @param classtree the data structure representing the class tree.
*/
protected void generateOtherFiles(RootDoc root, ClassTree classtree) throws Exception {
BuilderFactory builderFactory = configuration.getBuilderFactory();
AbstractBuilder constantsSummaryBuilder = builderFactory.getConstantsSummaryBuider();
constantsSummaryBuilder.build();
AbstractBuilder serializedFormBuilder = builderFactory.getSerializedFormBuilder();
serializedFormBuilder.build();
}
/**
* Generate the profile documentation.
*
*/
protected abstract void generateProfileFiles() throws Exception;
/**
* Generate the package documentation.
*
* @param classtree the data structure representing the class tree.
*/
protected abstract void generatePackageFiles(ClassTree classtree) throws Exception;
/**
* Generate the class documentation.
*
* @param classtree the data structure representing the class tree.
*/
protected abstract void generateClassFiles(ClassDoc[] arr, ClassTree classtree);
/**
* Iterate through all classes and construct documentation for them.
*
* @param root the RootDoc of source to document.
* @param classtree the data structure representing the class tree.
*/
protected void generateClassFiles(RootDoc root, ClassTree classtree) {
generateClassFiles(classtree);
PackageDoc[] packages = root.specifiedPackages();
for (int i = 0; i < packages.length; i++) {
generateClassFiles(packages[i].allClasses(), classtree);
}
}
/**
* Generate the class files for single classes specified on the command line.
*
* @param classtree the data structure representing the class tree.
*/
private void generateClassFiles(ClassTree classtree) {
String[] packageNames = configuration.classDocCatalog.packageNames();
for (int packageNameIndex = 0; packageNameIndex < packageNames.length;
packageNameIndex++) {
generateClassFiles(configuration.classDocCatalog.allClasses(
packageNames[packageNameIndex]), classtree);
}
}
}

132
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/AnnotationTypeFieldWriter.java Normal file
View File

@@ -0,0 +1,132 @@
/*
* Copyright (c) 2013, 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 com.sun.tools.doclets.internal.toolkit;
import java.io.*;
import com.sun.javadoc.*;
/**
* The interface for writing annotation type field output.
*
* <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 Bhavesh Patel
* @since 1.8
*/
public interface AnnotationTypeFieldWriter {
/**
* Add the annotation type member tree header.
*
* @return content tree for the member tree header
*/
public Content getMemberTreeHeader();
/**
* Add the annotation type field details marker.
*
* @param memberDetails the content tree representing field details marker
*/
public void addAnnotationFieldDetailsMarker(Content memberDetails);
/**
* Add the annotation type details tree header.
*
* @param classDoc the annotation type being documented
* @param memberDetailsTree the content tree representing member details
*/
public void addAnnotationDetailsTreeHeader(ClassDoc classDoc,
Content memberDetailsTree);
/**
* Get the annotation type documentation tree header.
*
* @param member the annotation type being documented
* @param annotationDetailsTree the content tree representing annotation type details
* @return content tree for the annotation type documentation header
*/
public Content getAnnotationDocTreeHeader(MemberDoc member,
Content annotationDetailsTree);
/**
* Get the annotation type details tree.
*
* @param annotationDetailsTree the content tree representing annotation type details
* @return content tree for the annotation type details
*/
public Content getAnnotationDetails(Content annotationDetailsTree);
/**
* Get the annotation type documentation.
*
* @param annotationDocTree the content tree representing annotation type documentation
* @param isLastContent true if the content to be added is the last content
* @return content tree for the annotation type documentation
*/
public Content getAnnotationDoc(Content annotationDocTree, boolean isLastContent);
/**
* Get the signature for the given member.
*
* @param member the member being documented
* @return content tree for the annotation type signature
*/
public Content getSignature(MemberDoc member);
/**
* Add the deprecated output for the given member.
*
* @param member the member being documented
* @param annotationDocTree content tree to which the deprecated information will be added
*/
public void addDeprecated(MemberDoc member, Content annotationDocTree);
/**
* Add the comments for the given member.
*
* @param member the member being documented
* @param annotationDocTree the content tree to which the comments will be added
*/
public void addComments(MemberDoc member, Content annotationDocTree);
/**
* Add the tags for the given member.
*
* @param member the member being documented
* @param annotationDocTree the content tree to which the tags will be added
*/
public void addTags(MemberDoc member, Content annotationDocTree);
/**
* Close the writer.
*/
public void close() throws IOException;
}

53
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/AnnotationTypeOptionalMemberWriter.java Normal file
View File

@@ -0,0 +1,53 @@
/*
* Copyright (c) 2003, 2012, 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 com.sun.tools.doclets.internal.toolkit;
import com.sun.javadoc.*;
/**
* The interface for writing annotation type optional member output.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public interface AnnotationTypeOptionalMemberWriter extends
AnnotationTypeRequiredMemberWriter {
/**
* Add the the default value documentation.
*
* @param member the member being documented
* @param annotationDocTree content tree to which the default value will be added
*/
public void addDefaultValueInfo(MemberDoc member, Content annotationDocTree);
}

133
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/AnnotationTypeRequiredMemberWriter.java Normal file
View File

@@ -0,0 +1,133 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit;
import java.io.*;
import com.sun.javadoc.*;
/**
* The interface for writing annotation type required member output.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public interface AnnotationTypeRequiredMemberWriter {
/**
* Add the annotation type member tree header.
*
* @return content tree for the member tree header
*/
public Content getMemberTreeHeader();
/**
* Add the annotation type details marker.
*
* @param memberDetails the content tree representing details marker
*/
public void addAnnotationDetailsMarker(Content memberDetails);
/**
* Add the annotation type details tree header.
*
* @param classDoc the annotation type being documented
* @param memberDetailsTree the content tree representing member details
*/
public void addAnnotationDetailsTreeHeader(ClassDoc classDoc,
Content memberDetailsTree);
/**
* Get the annotation type documentation tree header.
*
* @param member the annotation type being documented
* @param annotationDetailsTree the content tree representing annotation type details
* @return content tree for the annotation type documentation header
*/
public Content getAnnotationDocTreeHeader(MemberDoc member,
Content annotationDetailsTree);
/**
* Get the annotation type details tree.
*
* @param annotationDetailsTree the content tree representing annotation type details
* @return content tree for the annotation type details
*/
public Content getAnnotationDetails(Content annotationDetailsTree);
/**
* Get the annotation type documentation.
*
* @param annotationDocTree the content tree representing annotation type documentation
* @param isLastContent true if the content to be added is the last content
* @return content tree for the annotation type documentation
*/
public Content getAnnotationDoc(Content annotationDocTree, boolean isLastContent);
/**
* Get the signature for the given member.
*
* @param member the member being documented
* @return content tree for the annotation type signature
*/
public Content getSignature(MemberDoc member);
/**
* Add the deprecated output for the given member.
*
* @param member the member being documented
* @param annotationDocTree content tree to which the deprecated information will be added
*/
public void addDeprecated(MemberDoc member, Content annotationDocTree);
/**
* Add the comments for the given member.
*
* @param member the member being documented
* @param annotationDocTree the content tree to which the comments will be added
*/
public void addComments(MemberDoc member, Content annotationDocTree);
/**
* Add the tags for the given member.
*
* @param member the member being documented
* @param annotationDocTree the content tree to which the tags will be added
*/
public void addTags(MemberDoc member, Content annotationDocTree);
/**
* Close the writer.
*/
public void close() throws IOException;
}

162
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/AnnotationTypeWriter.java Normal file
View File

@@ -0,0 +1,162 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit;
import java.io.*;
import com.sun.javadoc.*;
/**
* The interface for writing annotation type output.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public interface AnnotationTypeWriter {
/**
* Get the header of the page.
*
* @param header the header string to write
* @return a content tree for the header documentation
*/
public Content getHeader(String header);
/**
* Get the annotation content header.
*
* @return annotation content header that needs to be added to the documentation
*/
public Content getAnnotationContentHeader();
/**
* Get the annotation information tree header.
*
* @return annotation information tree header that needs to be added to the documentation
*/
public Content getAnnotationInfoTreeHeader();
/**
* Get the annotation information.
*
* @param annotationInfoTree content tree containing the annotation information
* @return a content tree for the annotation
*/
public Content getAnnotationInfo(Content annotationInfoTree);
/**
* Add the signature of the current annotation type.
*
* @param modifiers the modifiers for the signature
* @param annotationInfoTree the annotation content tree to which the signature will be added
*/
public void addAnnotationTypeSignature(String modifiers, Content annotationInfoTree);
/**
* Build the annotation type description.
*
* @param annotationInfoTree content tree to which the description will be added
*/
public void addAnnotationTypeDescription(Content annotationInfoTree);
/**
* Add the tag information for the current annotation type.
*
* @param annotationInfoTree content tree to which the tag information will be added
*/
public void addAnnotationTypeTagInfo(Content annotationInfoTree);
/**
* If this annotation is deprecated, add the appropriate information.
*
* @param annotationInfoTree content tree to which the deprecated information will be added
*/
public void addAnnotationTypeDeprecationInfo (Content annotationInfoTree);
/**
* Get the member tree header for the annotation type.
*
* @return a content tree for the member tree header
*/
public Content getMemberTreeHeader();
/**
* Get the member tree.
*
* @param memberTree the content tree that will be modified and returned
* @return a content tree for the member
*/
public Content getMemberTree(Content memberTree);
/**
* Get the member summary tree.
*
* @param memberTree the content tree that will be used to build the summary tree
* @return a content tree for the member summary
*/
public Content getMemberSummaryTree(Content memberTree);
/**
* Get the member details tree.
*
* @param memberTree the content tree that will be used to build the details tree
* @return a content tree for the member details
*/
public Content getMemberDetailsTree(Content memberTree);
/**
* Add the footer of the page.
*
* @param contentTree content tree to which the footer will be added
*/
public void addFooter(Content contentTree);
/**
* Print the document.
*
* @param contentTree content tree that will be printed as a document
*/
public void printDocument(Content contentTree) throws IOException;
/**
* Close the writer.
*/
public void close() throws IOException;
/**
* Return the {@link AnnotationTypeDoc} being documented.
*
* @return the AnnotationTypeDoc being documented.
*/
public AnnotationTypeDoc getAnnotationTypeDoc();
}

219
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/ClassWriter.java Normal file
View File

@@ -0,0 +1,219 @@
/*
* Copyright (c) 2003, 2012, 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 com.sun.tools.doclets.internal.toolkit;
import java.io.*;
import com.sun.javadoc.*;
/**
* The interface for writing class output.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public interface ClassWriter {
/**
* Get the header of the page.
*
* @param header the header string to write
* @return header content that needs to be added to the documentation
*/
public Content getHeader(String header);
/**
* Get the class content header.
*
* @return class content header that needs to be added to the documentation
*/
public Content getClassContentHeader();
/**
* Add the class tree documentation.
*
* @param classContentTree class content tree to which the documentation will be added
*/
public void addClassTree(Content classContentTree);
/**
* Get the class information tree header.
*
* @return class informaion tree header that needs to be added to the documentation
*/
public Content getClassInfoTreeHeader();
/**
* Add the type parameter information.
*
* @param classInfoTree content tree to which the documentation will be added
*/
public void addTypeParamInfo(Content classInfoTree);
/**
* Add all super interfaces if this is an interface.
*
* @param classInfoTree content tree to which the documentation will be added
*/
public void addSuperInterfacesInfo(Content classInfoTree);
/**
* Add all implemented interfaces if this is a class.
*
* @param classInfoTree content tree to which the documentation will be added
*/
public void addImplementedInterfacesInfo(Content classInfoTree);
/**
* Add all the classes that extend this one.
*
* @param classInfoTree content tree to which the documentation will be added
*/
public void addSubClassInfo(Content classInfoTree);
/**
* Add all the interfaces that extend this one.
*
* @param classInfoTree content tree to which the documentation will be added
*/
public void addSubInterfacesInfo(Content classInfoTree);
/**
* If this is an interface, add all classes that implement this
* interface.
*
* @param classInfoTree content tree to which the documentation will be added
*/
public void addInterfaceUsageInfo(Content classInfoTree);
/**
* If this is an functional interface, display appropriate message.
*
* @param classInfoTree content tree to which the documentation will be added
*/
public void addFunctionalInterfaceInfo(Content classInfoTree);
/**
* If this is an inner class or interface, add the enclosing class or
* interface.
*
* @param classInfoTree content tree to which the documentation will be added
*/
public void addNestedClassInfo (Content classInfoTree);
/**
* Get the class information.
*
* @param classInfoTree content tree conatining the class information
* @return a content tree for the class
*/
public Content getClassInfo(Content classInfoTree);
/**
* If this class is deprecated, add the appropriate information.
*
* @param classInfoTree content tree to which the documentation will be added
*/
public void addClassDeprecationInfo (Content classInfoTree);
/**
* Add the signature of the current class content tree.
*
* @param modifiers the modifiers for the signature
* @param classInfoTree the class content tree to which the signature will be added
*/
public void addClassSignature(String modifiers, Content classInfoTree);
/**
* Build the class description.
*
* @param classInfoTree content tree to which the documentation will be added
*/
public void addClassDescription(Content classInfoTree);
/**
* Add the tag information for the current class.
*
* @param classInfoTree content tree to which the tag information will be added
*/
public void addClassTagInfo(Content classInfoTree);
/**
* Get the member tree header for the class.
*
* @return a content tree for the member tree header
*/
public Content getMemberTreeHeader();
/**
* Add the footer of the page.
*
* @param contentTree content tree to which the footer will be added
*/
public void addFooter(Content contentTree);
/**
* Print the document.
*
* @param contentTree content tree that will be printed as a document
*/
public void printDocument(Content contentTree) throws IOException;
/**
* Close the writer.
*/
public void close() throws IOException;
/**
* Return the classDoc being documented.
*
* @return the classDoc being documented.
*/
public ClassDoc getClassDoc();
/**
* Get the member summary tree.
*
* @param memberTree the content tree used to build the summary tree
* @return a content tree for the member summary
*/
public Content getMemberSummaryTree(Content memberTree);
/**
* Get the member details tree.
*
* @param memberTree the content tree used to build the details tree
* @return a content tree for the member details
*/
public Content getMemberDetailsTree(Content memberTree);
}

989
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/Configuration.java Normal file
View File

@@ -0,0 +1,989 @@
/*
* Copyright (c) 1997, 2013, 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 com.sun.tools.doclets.internal.toolkit;
import java.io.*;
import java.util.*;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import javax.tools.JavaFileManager;
import com.sun.javadoc.*;
import com.sun.tools.javac.sym.Profiles;
import com.sun.tools.javac.jvm.Profile;
import com.sun.tools.doclets.internal.toolkit.builders.BuilderFactory;
import com.sun.tools.doclets.internal.toolkit.taglets.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
import com.sun.tools.javac.util.StringUtils;
/**
* Configure the output based on the options. Doclets should sub-class
* Configuration, to configure and add their own options. This class contains
* all user options which are supported by the 1.1 doclet and the standard
* doclet.
*
* <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 Robert Field.
* @author Atul Dambalkar.
* @author Jamie Ho
*/
public abstract class Configuration {
/**
* Exception used to report a problem during setOptions.
*/
public static class Fault extends Exception {
private static final long serialVersionUID = 0;
Fault(String msg) {
super(msg);
}
Fault(String msg, Exception cause) {
super(msg, cause);
}
}
/**
* The factory for builders.
*/
protected BuilderFactory builderFactory;
/**
* The taglet manager.
*/
public TagletManager tagletManager;
/**
* The path to the builder XML input file.
*/
public String builderXMLPath;
/**
* The default path to the builder XML.
*/
private static final String DEFAULT_BUILDER_XML = "resources/doclet.xml";
/**
* The path to Taglets
*/
public String tagletpath = "";
/**
* This is true if option "-serialwarn" is used. Defualt value is false to
* suppress excessive warnings about serial tag.
*/
public boolean serialwarn = false;
/**
* The specified amount of space between tab stops.
*/
public int sourcetab;
public String tabSpaces;
/**
* True if we should generate browsable sources.
*/
public boolean linksource = false;
/**
* True if command line option "-nosince" is used. Default value is
* false.
*/
public boolean nosince = false;
/**
* True if we should recursively copy the doc-file subdirectories
*/
public boolean copydocfilesubdirs = false;
/**
* The META charset tag used for cross-platform viewing.
*/
public String charset = "";
/**
* True if user wants to add member names as meta keywords.
* Set to false because meta keywords are ignored in general
* by most Internet search engines.
*/
public boolean keywords = false;
/**
* The meta tag keywords instance.
*/
public final MetaKeywords metakeywords = new MetaKeywords(this);
/**
* The list of doc-file subdirectories to exclude
*/
protected Set<String> excludedDocFileDirs;
/**
* The list of qualifiers to exclude
*/
protected Set<String> excludedQualifiers;
/**
* The Root of the generated Program Structure from the Doclet API.
*/
public RootDoc root;
/**
* Destination directory name, in which doclet will generate the entire
* documentation. Default is current directory.
*/
public String destDirName = "";
/**
* Destination directory name, in which doclet will copy the doc-files to.
*/
public String docFileDestDirName = "";
/**
* Encoding for this document. Default is default encoding for this
* platform.
*/
public String docencoding = null;
/**
* True if user wants to suppress descriptions and tags.
*/
public boolean nocomment = false;
/**
* Encoding for this document. Default is default encoding for this
* platform.
*/
public String encoding = null;
/**
* Generate author specific information for all the classes if @author
* tag is used in the doc comment and if -author option is used.
* <code>showauthor</code> is set to true if -author option is used.
* Default is don't show author information.
*/
public boolean showauthor = false;
/**
* Generate documentation for JavaFX getters and setters automatically
* by copying it from the appropriate property definition.
*/
public boolean javafx = false;
/**
* Generate version specific information for the all the classes
* if @version tag is used in the doc comment and if -version option is
* used. <code>showversion</code> is set to true if -version option is
* used.Default is don't show version information.
*/
public boolean showversion = false;
/**
* Sourcepath from where to read the source files. Default is classpath.
*
*/
public String sourcepath = "";
/**
* Argument for command line option "-Xprofilespath".
*/
public String profilespath = "";
/**
* Generate profiles documentation if profilespath is set and valid profiles
* are present.
*/
public boolean showProfiles = false;
/**
* Don't generate deprecated API information at all, if -nodeprecated
* option is used. <code>nodepracted</code> is set to true if
* -nodeprecated option is used. Default is generate deprected API
* information.
*/
public boolean nodeprecated = false;
/**
* The catalog of classes specified on the command-line
*/
public ClassDocCatalog classDocCatalog;
/**
* Message Retriever for the doclet, to retrieve message from the resource
* file for this Configuration, which is common for 1.1 and standard
* doclets.
*
* TODO: Make this private!!!
*/
public MessageRetriever message = null;
/**
* True if user wants to suppress time stamp in output.
* Default is false.
*/
public boolean notimestamp= false;
/**
* The package grouping instance.
*/
public final Group group = new Group(this);
/**
* The tracker of external package links.
*/
public final Extern extern = new Extern(this);
/**
* Return the build date for the doclet.
*/
public abstract String getDocletSpecificBuildDate();
/**
* This method should be defined in all those doclets(configurations),
* which want to derive themselves from this Configuration. This method
* can be used to set its own command line options.
*
* @param options The array of option names and values.
* @throws DocletAbortException
*/
public abstract void setSpecificDocletOptions(String[][] options) throws Fault;
/**
* Return the doclet specific {@link MessageRetriever}
* @return the doclet specific MessageRetriever.
*/
public abstract MessageRetriever getDocletSpecificMsg();
/**
* A profiles object used to access profiles across various pages.
*/
public Profiles profiles;
/**
* An map of the profiles to packages.
*/
public Map<String,PackageDoc[]> profilePackages;
/**
* An array of the packages specified on the command-line merged
* with the array of packages that contain the classes specified on the
* command-line. The array is sorted.
*/
public PackageDoc[] packages;
/**
* Constructor. Constructs the message retriever with resource file.
*/
public Configuration() {
message =
new MessageRetriever(this,
"com.sun.tools.doclets.internal.toolkit.resources.doclets");
excludedDocFileDirs = new HashSet<String>();
excludedQualifiers = new HashSet<String>();
setTabWidth(DocletConstants.DEFAULT_TAB_STOP_LENGTH);
}
/**
* Return the builder factory for this doclet.
*
* @return the builder factory for this doclet.
*/
public BuilderFactory getBuilderFactory() {
if (builderFactory == null) {
builderFactory = new BuilderFactory(this);
}
return builderFactory;
}
/**
* This method should be defined in all those doclets
* which want to inherit from this Configuration. This method
* should return the number of arguments to the command line
* option (including the option name). For example,
* -notimestamp is a single-argument option, so this method would
* return 1.
*
* @param option Command line option under consideration.
* @return number of arguments to option (including the
* option name). Zero return means option not known.
* Negative value means error occurred.
*/
public int optionLength(String option) {
option = StringUtils.toLowerCase(option);
if (option.equals("-author") ||
option.equals("-docfilessubdirs") ||
option.equals("-javafx") ||
option.equals("-keywords") ||
option.equals("-linksource") ||
option.equals("-nocomment") ||
option.equals("-nodeprecated") ||
option.equals("-nosince") ||
option.equals("-notimestamp") ||
option.equals("-quiet") ||
option.equals("-xnodate") ||
option.equals("-version")) {
return 1;
} else if (option.equals("-d") ||
option.equals("-docencoding") ||
option.equals("-encoding") ||
option.equals("-excludedocfilessubdir") ||
option.equals("-link") ||
option.equals("-sourcetab") ||
option.equals("-noqualifier") ||
option.equals("-output") ||
option.equals("-sourcepath") ||
option.equals("-tag") ||
option.equals("-taglet") ||
option.equals("-tagletpath") ||
option.equals("-xprofilespath")) {
return 2;
} else if (option.equals("-group") ||
option.equals("-linkoffline")) {
return 3;
} else {
return -1; // indicate we don't know about it
}
}
/**
* Perform error checking on the given options.
*
* @param options the given options to check.
* @param reporter the reporter used to report errors.
*/
public abstract boolean validOptions(String options[][],
DocErrorReporter reporter);
private void initProfiles() throws IOException {
if (profilespath.isEmpty())
return;
profiles = Profiles.read(new File(profilespath));
// Group the packages to be documented by the lowest profile (if any)
// in which each appears
Map<Profile, List<PackageDoc>> interimResults =
new EnumMap<Profile, List<PackageDoc>>(Profile.class);
for (Profile p: Profile.values())
interimResults.put(p, new ArrayList<PackageDoc>());
for (PackageDoc pkg: packages) {
if (nodeprecated && Util.isDeprecated(pkg)) {
continue;
}
// the getProfile method takes a type name, not a package name,
// but isn't particularly fussy about the simple name -- so just use *
int i = profiles.getProfile(pkg.name().replace(".", "/") + "/*");
Profile p = Profile.lookup(i);
if (p != null) {
List<PackageDoc> pkgs = interimResults.get(p);
pkgs.add(pkg);
}
}
// Build the profilePackages structure used by the doclet
profilePackages = new HashMap<String,PackageDoc[]>();
List<PackageDoc> prev = Collections.<PackageDoc>emptyList();
int size;
for (Map.Entry<Profile,List<PackageDoc>> e: interimResults.entrySet()) {
Profile p = e.getKey();
List<PackageDoc> pkgs = e.getValue();
pkgs.addAll(prev); // each profile contains all lower profiles
Collections.sort(pkgs);
size = pkgs.size();
// For a profile, if there are no packages to be documented, do not add
// it to profilePackages map.
if (size > 0)
profilePackages.put(p.name, pkgs.toArray(new PackageDoc[pkgs.size()]));
prev = pkgs;
}
// Generate profiles documentation if any profile contains any
// of the packages to be documented.
showProfiles = !prev.isEmpty();
}
private void initPackageArray() {
Set<PackageDoc> set = new HashSet<PackageDoc>(Arrays.asList(root.specifiedPackages()));
ClassDoc[] classes = root.specifiedClasses();
for (int i = 0; i < classes.length; i++) {
set.add(classes[i].containingPackage());
}
ArrayList<PackageDoc> results = new ArrayList<PackageDoc>(set);
Collections.sort(results);
packages = results.toArray(new PackageDoc[] {});
}
/**
* Set the command line options supported by this configuration.
*
* @param options the two dimensional array of options.
*/
public void setOptions(String[][] options) throws Fault {
LinkedHashSet<String[]> customTagStrs = new LinkedHashSet<String[]>();
// Some options, specifically -link and -linkoffline, require that
// the output directory has already been created: so do that first.
for (int oi = 0; oi < options.length; ++oi) {
String[] os = options[oi];
String opt = StringUtils.toLowerCase(os[0]);
if (opt.equals("-d")) {
destDirName = addTrailingFileSep(os[1]);
docFileDestDirName = destDirName;
ensureOutputDirExists();
break;
}
}
for (int oi = 0; oi < options.length; ++oi) {
String[] os = options[oi];
String opt = StringUtils.toLowerCase(os[0]);
if (opt.equals("-docfilessubdirs")) {
copydocfilesubdirs = true;
} else if (opt.equals("-docencoding")) {
docencoding = os[1];
} else if (opt.equals("-encoding")) {
encoding = os[1];
} else if (opt.equals("-author")) {
showauthor = true;
} else if (opt.equals("-javafx")) {
javafx = true;
} else if (opt.equals("-nosince")) {
nosince = true;
} else if (opt.equals("-version")) {
showversion = true;
} else if (opt.equals("-nodeprecated")) {
nodeprecated = true;
} else if (opt.equals("-sourcepath")) {
sourcepath = os[1];
} else if ((opt.equals("-classpath") || opt.equals("-cp")) &&
sourcepath.length() == 0) {
sourcepath = os[1];
} else if (opt.equals("-excludedocfilessubdir")) {
addToSet(excludedDocFileDirs, os[1]);
} else if (opt.equals("-noqualifier")) {
addToSet(excludedQualifiers, os[1]);
} else if (opt.equals("-linksource")) {
linksource = true;
} else if (opt.equals("-sourcetab")) {
linksource = true;
try {
setTabWidth(Integer.parseInt(os[1]));
} catch (NumberFormatException e) {
//Set to -1 so that warning will be printed
//to indicate what is valid argument.
sourcetab = -1;
}
if (sourcetab <= 0) {
message.warning("doclet.sourcetab_warning");
setTabWidth(DocletConstants.DEFAULT_TAB_STOP_LENGTH);
}
} else if (opt.equals("-notimestamp")) {
notimestamp = true;
} else if (opt.equals("-nocomment")) {
nocomment = true;
} else if (opt.equals("-tag") || opt.equals("-taglet")) {
customTagStrs.add(os);
} else if (opt.equals("-tagletpath")) {
tagletpath = os[1];
} else if (opt.equals("-xprofilespath")) {
profilespath = os[1];
} else if (opt.equals("-keywords")) {
keywords = true;
} else if (opt.equals("-serialwarn")) {
serialwarn = true;
} else if (opt.equals("-group")) {
group.checkPackageGroups(os[1], os[2]);
} else if (opt.equals("-link")) {
String url = os[1];
extern.link(url, url, root, false);
} else if (opt.equals("-linkoffline")) {
String url = os[1];
String pkglisturl = os[2];
extern.link(url, pkglisturl, root, true);
}
}
if (sourcepath.length() == 0) {
sourcepath = System.getProperty("env.class.path") == null ? "" :
System.getProperty("env.class.path");
}
if (docencoding == null) {
docencoding = encoding;
}
classDocCatalog = new ClassDocCatalog(root.specifiedClasses(), this);
initTagletManager(customTagStrs);
}
/**
* Set the command line options supported by this configuration.
*
* @throws DocletAbortException
*/
public void setOptions() throws Fault {
initPackageArray();
setOptions(root.options());
try {
initProfiles();
} catch (Exception e) {
throw new DocletAbortException(e);
}
setSpecificDocletOptions(root.options());
}
private void ensureOutputDirExists() throws Fault {
DocFile destDir = DocFile.createFileForDirectory(this, destDirName);
if (!destDir.exists()) {
//Create the output directory (in case it doesn't exist yet)
root.printNotice(getText("doclet.dest_dir_create", destDirName));
destDir.mkdirs();
} else if (!destDir.isDirectory()) {
throw new Fault(getText(
"doclet.destination_directory_not_directory_0",
destDir.getPath()));
} else if (!destDir.canWrite()) {
throw new Fault(getText(
"doclet.destination_directory_not_writable_0",
destDir.getPath()));
}
}
/**
* Initialize the taglet manager. The strings to initialize the simple custom tags should
* be in the following format: "[tag name]:[location str]:[heading]".
* @param customTagStrs the set two dimensional arrays of strings. These arrays contain
* either -tag or -taglet arguments.
*/
private void initTagletManager(Set<String[]> customTagStrs) {
tagletManager = tagletManager == null ?
new TagletManager(nosince, showversion, showauthor, javafx, message) :
tagletManager;
String[] args;
for (Iterator<String[]> it = customTagStrs.iterator(); it.hasNext(); ) {
args = it.next();
if (args[0].equals("-taglet")) {
tagletManager.addCustomTag(args[1], getFileManager(), tagletpath);
continue;
}
String[] tokens = tokenize(args[1],
TagletManager.SIMPLE_TAGLET_OPT_SEPARATOR, 3);
if (tokens.length == 1) {
String tagName = args[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.length == 2) {
//Add simple taglet without heading, probably to excluding it in the output.
tagletManager.addNewSimpleCustomTag(tokens[0], tokens[1], "");
} else if (tokens.length >= 3) {
tagletManager.addNewSimpleCustomTag(tokens[0], tokens[2], tokens[1]);
} else {
message.error("doclet.Error_invalid_custom_tag_argument", args[1]);
}
}
}
/**
* Given a string, return an array of tokens. The separator can be escaped
* with the '\' character. The '\' character may also be escaped by the
* '\' character.
*
* @param s the string to tokenize.
* @param separator the separator char.
* @param maxTokens the maximum number of tokens returned. If the
* max is reached, the remaining part of s is appended
* to the end of the last token.
*
* @return an array of tokens.
*/
private String[] tokenize(String s, char separator, int maxTokens) {
List<String> tokens = new ArrayList<String>();
StringBuilder token = new StringBuilder ();
boolean prevIsEscapeChar = false;
for (int i = 0; i < s.length(); i += Character.charCount(i)) {
int currentChar = s.codePointAt(i);
if (prevIsEscapeChar) {
// Case 1: escaped character
token.appendCodePoint(currentChar);
prevIsEscapeChar = false;
} else if (currentChar == separator && tokens.size() < maxTokens-1) {
// Case 2: separator
tokens.add(token.toString());
token = new StringBuilder();
} else if (currentChar == '\\') {
// Case 3: escape character
prevIsEscapeChar = true;
} else {
// Case 4: regular character
token.appendCodePoint(currentChar);
}
}
if (token.length() > 0) {
tokens.add(token.toString());
}
return tokens.toArray(new String[] {});
}
private void addToSet(Set<String> s, String str){
StringTokenizer st = new StringTokenizer(str, ":");
String current;
while(st.hasMoreTokens()){
current = st.nextToken();
s.add(current);
}
}
/**
* Add a trailing file separator, if not found. Remove superfluous
* file separators if any. Preserve the front double file separator for
* UNC paths.
*
* @param path Path under consideration.
* @return String Properly constructed path string.
*/
public static String addTrailingFileSep(String path) {
String fs = System.getProperty("file.separator");
String dblfs = fs + fs;
int indexDblfs;
while ((indexDblfs = path.indexOf(dblfs, 1)) >= 0) {
path = path.substring(0, indexDblfs) +
path.substring(indexDblfs + fs.length());
}
if (!path.endsWith(fs))
path += fs;
return path;
}
/**
* This checks for the validity of the options used by the user.
* This works exactly like
* {@link com.sun.javadoc.Doclet#validOptions(String[][],
* DocErrorReporter)}. This will validate the options which are shared
* by our doclets. For example, this method will flag an error using
* the DocErrorReporter if user has used "-nohelp" and "-helpfile" option
* together.
*
* @param options options used on the command line.
* @param reporter used to report errors.
* @return true if all the options are valid.
*/
public boolean generalValidOptions(String options[][],
DocErrorReporter reporter) {
boolean docencodingfound = false;
String encoding = "";
for (int oi = 0; oi < options.length; oi++) {
String[] os = options[oi];
String opt = StringUtils.toLowerCase(os[0]);
if (opt.equals("-docencoding")) {
docencodingfound = true;
if (!checkOutputFileEncoding(os[1], reporter)) {
return false;
}
} else if (opt.equals("-encoding")) {
encoding = os[1];
}
}
if (!docencodingfound && encoding.length() > 0) {
if (!checkOutputFileEncoding(encoding, reporter)) {
return false;
}
}
return true;
}
/**
* Check the validity of the given profile. Return false if there are no
* valid packages to be documented for the profile.
*
* @param profileName the profile that needs to be validated.
* @return true if the profile has valid packages to be documented.
*/
public boolean shouldDocumentProfile(String profileName) {
return profilePackages.containsKey(profileName);
}
/**
* Check the validity of the given Source or Output File encoding on this
* platform.
*
* @param docencoding output file encoding.
* @param reporter used to report errors.
*/
private boolean checkOutputFileEncoding(String docencoding,
DocErrorReporter reporter) {
OutputStream ost= new ByteArrayOutputStream();
OutputStreamWriter osw = null;
try {
osw = new OutputStreamWriter(ost, docencoding);
} catch (UnsupportedEncodingException exc) {
reporter.printError(getText("doclet.Encoding_not_supported",
docencoding));
return false;
} finally {
try {
if (osw != null) {
osw.close();
}
} catch (IOException exc) {
}
}
return true;
}
/**
* Return true if the given doc-file subdirectory should be excluded and
* false otherwise.
* @param docfilesubdir the doc-files subdirectory to check.
*/
public boolean shouldExcludeDocFileDir(String docfilesubdir){
if (excludedDocFileDirs.contains(docfilesubdir)) {
return true;
} else {
return false;
}
}
/**
* Return true if the given qualifier should be excluded and false otherwise.
* @param qualifier the qualifier to check.
*/
public boolean shouldExcludeQualifier(String qualifier){
if (excludedQualifiers.contains("all") ||
excludedQualifiers.contains(qualifier) ||
excludedQualifiers.contains(qualifier + ".*")) {
return true;
} else {
int index = -1;
while ((index = qualifier.indexOf(".", index + 1)) != -1) {
if (excludedQualifiers.contains(qualifier.substring(0, index + 1) + "*")) {
return true;
}
}
return false;
}
}
/**
* Return the qualified name of the <code>ClassDoc</code> if it's qualifier is not excluded. Otherwise,
* return the unqualified <code>ClassDoc</code> name.
* @param cd the <code>ClassDoc</code> to check.
*/
public String getClassName(ClassDoc cd) {
PackageDoc pd = cd.containingPackage();
if (pd != null && shouldExcludeQualifier(cd.containingPackage().name())) {
return cd.name();
} else {
return cd.qualifiedName();
}
}
public String getText(String key) {
try {
//Check the doclet specific properties file.
return getDocletSpecificMsg().getText(key);
} catch (Exception e) {
//Check the shared properties file.
return message.getText(key);
}
}
public String getText(String key, String a1) {
try {
//Check the doclet specific properties file.
return getDocletSpecificMsg().getText(key, a1);
} catch (Exception e) {
//Check the shared properties file.
return message.getText(key, a1);
}
}
public String getText(String key, String a1, String a2) {
try {
//Check the doclet specific properties file.
return getDocletSpecificMsg().getText(key, a1, a2);
} catch (Exception e) {
//Check the shared properties file.
return message.getText(key, a1, a2);
}
}
public String getText(String key, String a1, String a2, String a3) {
try {
//Check the doclet specific properties file.
return getDocletSpecificMsg().getText(key, a1, a2, a3);
} catch (Exception e) {
//Check the shared properties file.
return message.getText(key, a1, a2, a3);
}
}
public abstract Content newContent();
/**
* Get the configuration string as a content.
*
* @param key the key to look for in the configuration file
* @return a content tree for the text
*/
public Content getResource(String key) {
Content c = newContent();
c.addContent(getText(key));
return c;
}
/**
* Get the configuration string as a content.
*
* @param key the key to look for in the configuration file
* @param o string or content argument added to configuration text
* @return a content tree for the text
*/
public Content getResource(String key, Object o) {
return getResource(key, o, null, null);
}
/**
* Get the configuration string as a content.
*
* @param key the key to look for in the configuration file
* @param o string or content argument added to configuration text
* @return a content tree for the text
*/
public Content getResource(String key, Object o1, Object o2) {
return getResource(key, o1, o2, null);
}
/**
* Get the configuration string as a content.
*
* @param key the key to look for in the configuration file
* @param o1 string or content argument added to configuration text
* @param o2 string or content argument added to configuration text
* @return a content tree for the text
*/
public Content getResource(String key, Object o0, Object o1, Object o2) {
Content c = newContent();
Pattern p = Pattern.compile("\\{([012])\\}");
String text = getText(key);
Matcher m = p.matcher(text);
int start = 0;
while (m.find(start)) {
c.addContent(text.substring(start, m.start()));
Object o = null;
switch (m.group(1).charAt(0)) {
case '0': o = o0; break;
case '1': o = o1; break;
case '2': o = o2; break;
}
if (o == null) {
c.addContent("{" + m.group(1) + "}");
} else if (o instanceof String) {
c.addContent((String) o);
} else if (o instanceof Content) {
c.addContent((Content) o);
}
start = m.end();
}
c.addContent(text.substring(start));
return c;
}
/**
* Return true if the ClassDoc element is getting documented, depending upon
* -nodeprecated option and the deprecation information. Return true if
* -nodeprecated is not used. Return false if -nodeprecated is used and if
* either ClassDoc element is deprecated or the containing package is deprecated.
*
* @param cd the ClassDoc for which the page generation is checked
*/
public boolean isGeneratedDoc(ClassDoc cd) {
if (!nodeprecated) {
return true;
}
return !(Util.isDeprecated(cd) || Util.isDeprecated(cd.containingPackage()));
}
/**
* Return the doclet specific instance of a writer factory.
* @return the {@link WriterFactory} for the doclet.
*/
public abstract WriterFactory getWriterFactory();
/**
* Return the input stream to the builder XML.
*
* @return the input steam to the builder XML.
* @throws FileNotFoundException when the given XML file cannot be found.
*/
public InputStream getBuilderXML() throws IOException {
return builderXMLPath == null ?
Configuration.class.getResourceAsStream(DEFAULT_BUILDER_XML) :
DocFile.createFileForInput(this, builderXMLPath).openInputStream();
}
/**
* Return the Locale for this document.
*/
public abstract Locale getLocale();
/**
* Return the current file manager.
*/
public abstract JavaFileManager getFileManager();
/**
* Return the comparator that will be used to sort member documentation.
* To no do any sorting, return null.
*
* @return the {@link java.util.Comparator} used to sort members.
*/
public abstract Comparator<ProgramElementDoc> getMemberComparator();
private void setTabWidth(int n) {
sourcetab = n;
tabSpaces = String.format("%" + n + "s", "");
}
public abstract boolean showMessage(SourcePosition pos, String key);
}

144
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/ConstantsSummaryWriter.java Normal file
View File

@@ -0,0 +1,144 @@
/*
* Copyright (c) 2003, 2012, 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 com.sun.tools.doclets.internal.toolkit;
import java.io.*;
import java.util.*;
import com.sun.javadoc.*;
/**
* The interface for writing constants summary output.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public interface ConstantsSummaryWriter {
/**
* Close the writer.
*/
public abstract void close() throws IOException;
/**
* Get the header for the constant summary documentation.
*
* @return header that needs to be added to the documentation
*/
public abstract Content getHeader();
/**
* Get the header for the constant content list.
*
* @return content header that needs to be added to the documentation
*/
public abstract Content getContentsHeader();
/**
* Adds the given package name link to the constant content list tree.
*
* @param pkg the {@link PackageDoc} to index.
* @param parsedPackageName the parsed package name. We only Write the
* first 2 directory levels of the package
* name. For example, java.lang.ref would be
* indexed as java.lang.*.
* @param WriteedPackageHeaders the set of package headers that have already
* been indexed. We don't want to index
* something more than once.
* @param contentListTree the content tree to which the link will be added
*/
public abstract void addLinkToPackageContent(PackageDoc pkg, String parsedPackageName,
Set<String> WriteedPackageHeaders, Content contentListTree);
/**
* Get the content list to be added to the documentation tree.
*
* @param contentListTree the content that will be added to the list
* @return content list that will be added to the documentation tree
*/
public abstract Content getContentsList(Content contentListTree);
/**
* Get the constant summaries for the document.
*
* @return constant summaries header to be added to the documentation tree
*/
public abstract Content getConstantSummaries();
/**
* Adds the given package name.
*
* @param pkg the {@link PackageDoc} to index.
* @param parsedPackageName the parsed package name. We only Write the
* first 2 directory levels of the package
* name. For example, java.lang.ref would be
* indexed as java.lang.*.
* @param summariesTree the documentation tree to which the package name will
* be written
*/
public abstract void addPackageName(PackageDoc pkg,
String parsedPackageName, Content summariesTree);
/**
* Get the class summary header for the constants summary.
*
* @return the header content for the class constants summary
*/
public abstract Content getClassConstantHeader();
/**
* Adds the constant member table to the documentation tree.
*
* @param cd the class whose constants are being documented.
* @param fields the constants being documented.
* @param classConstantTree the documentation tree to which theconstant member
* table content will be added
*/
public abstract void addConstantMembers(ClassDoc cd, List<FieldDoc> fields,
Content classConstantTree);
/**
* Adds the footer for the summary documentation.
*
* @param contentTree content tree to which the footer will be added
*/
public abstract void addFooter(Content contentTree);
/**
* Print the constants summary document.
*
* @param contentTree content tree which should be printed
*/
public abstract void printDocument(Content contentTree) throws IOException;
}

126
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/ConstructorWriter.java Normal file
View File

@@ -0,0 +1,126 @@
/*
* Copyright (c) 2003, 2012, 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 com.sun.tools.doclets.internal.toolkit;
import java.io.*;
import com.sun.javadoc.*;
/**
* The interface for writing constructor output.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public interface ConstructorWriter {
/**
* Get the constructor details tree header.
*
* @param classDoc the class being documented
* @param memberDetailsTree the content tree representing member details
* @return content tree for the constructor details header
*/
public Content getConstructorDetailsTreeHeader(ClassDoc classDoc,
Content memberDetailsTree);
/**
* Get the constructor documentation tree header.
*
* @param constructor the constructor being documented
* @param constructorDetailsTree the content tree representing constructor details
* @return content tree for the constructor documentation header
*/
public Content getConstructorDocTreeHeader(ConstructorDoc constructor,
Content constructorDetailsTree);
/**
* Get the signature for the given constructor.
*
* @param constructor the constructor being documented
* @return content tree for the constructor signature
*/
public Content getSignature(ConstructorDoc constructor);
/**
* Add the deprecated output for the given constructor.
*
* @param constructor the constructor being documented
* @param constructorDocTree content tree to which the deprecated information will be added
*/
public void addDeprecated(ConstructorDoc constructor, Content constructorDocTree);
/**
* Add the comments for the given constructor.
*
* @param constructor the constructor being documented
* @param constructorDocTree the content tree to which the comments will be added
*/
public void addComments(ConstructorDoc constructor, Content constructorDocTree);
/**
* Add the tags for the given constructor.
*
* @param constructor the constructor being documented
* @param constructorDocTree the content tree to which the tags will be added
*/
public void addTags(ConstructorDoc constructor, Content constructorDocTree);
/**
* Get the constructor details tree.
*
* @param memberDetailsTree the content tree representing member details
* @return content tree for the constructor details
*/
public Content getConstructorDetails(Content memberDetailsTree);
/**
* Get the constructor documentation.
*
* @param constructorDocTree the content tree representing constructor documentation
* @param isLastContent true if the content to be added is the last content
* @return content tree for the constructor documentation
*/
public Content getConstructorDoc(Content constructorDocTree, boolean isLastContent);
/**
* Let the writer know whether a non public constructor was found.
*
* @param foundNonPubConstructor true if we found a non public constructor.
*/
public void setFoundNonPubConstructor(boolean foundNonPubConstructor);
/**
* Close the writer.
*/
public void close() throws IOException;
}

118
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/Content.java Normal file
View File

@@ -0,0 +1,118 @@
/*
* Copyright (c) 2010, 2013, 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 com.sun.tools.doclets.internal.toolkit;
import java.io.IOException;
import java.io.StringWriter;
import java.io.Writer;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* A class to create content for javadoc output pages.
*
* <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 Bhavesh Patel
*/
public abstract class Content {
/**
* Returns a string representation of the content.
*
* @return string representation of the content
*/
@Override
public String toString() {
StringWriter out = new StringWriter();
try {
write(out, true);
} catch (IOException e) {
// cannot happen from StringWriter
throw new DocletAbortException(e);
}
return out.toString();
}
/**
* Adds content to the existing content.
*
* @param content content that needs to be added
*/
public abstract void addContent(Content content);
/**
* Adds a string content to the existing content.
*
* @param stringContent the string content to be added
*/
public abstract void addContent(String stringContent);
/**
* Writes content to a writer.
*
*/
public abstract boolean write(Writer writer, boolean atNewline) throws IOException ;
/**
* Returns true if the content is empty.
*
* @return true if no content to be displayed else return false
*/
public abstract boolean isEmpty();
/**
* Returns true if the content is valid.
*
* @return true if the content is valid else return false
*/
public boolean isValid() {
return !isEmpty();
}
/**
* Return the number of characters of plain text content in this object
* (optional operation.)
* @return the number of characters of plain text content in this
*/
public int charCount() {
return 0;
}
/**
* Checks for null values.
*
* @param t reference type to check for null values
* @return the reference type if not null or else throws a null pointer exception
*/
protected static <T> T nullCheck(T t) {
t.getClass();
return t;
}
}

119
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/EnumConstantWriter.java Normal file
View File

@@ -0,0 +1,119 @@
/*
* Copyright (c) 2003, 2012, 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 com.sun.tools.doclets.internal.toolkit;
import java.io.*;
import com.sun.javadoc.*;
/**
* The interface for writing enum constant output.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public interface EnumConstantWriter {
/**
* Get the enum constants details tree header.
*
* @param classDoc the class being documented
* @param memberDetailsTree the content tree representing member details
* @return content tree for the enum constants details header
*/
public Content getEnumConstantsDetailsTreeHeader(ClassDoc classDoc,
Content memberDetailsTree);
/**
* Get the enum constants documentation tree header.
*
* @param enumConstant the enum constant being documented
* @param enumConstantsDetailsTree the content tree representing enum constant details
* @return content tree for the enum constant documentation header
*/
public Content getEnumConstantsTreeHeader(FieldDoc enumConstant,
Content enumConstantsDetailsTree);
/**
* Get the signature for the given enum constant.
*
* @param enumConstant the enum constant being documented
* @return content tree for the enum constant signature
*/
public Content getSignature(FieldDoc enumConstant);
/**
* Add the deprecated output for the given enum constant.
*
* @param enumConstant the enum constant being documented
* @param enumConstantsTree content tree to which the deprecated information will be added
*/
public void addDeprecated(FieldDoc enumConstant, Content enumConstantsTree);
/**
* Add the comments for the given enum constant.
*
* @param enumConstant the enum constant being documented
* @param enumConstantsTree the content tree to which the comments will be added
*/
public void addComments(FieldDoc enumConstant, Content enumConstantsTree);
/**
* Add the tags for the given enum constant.
*
* @param enumConstant the enum constant being documented
* @param enumConstantsTree the content tree to which the tags will be added
*/
public void addTags(FieldDoc enumConstant, Content enumConstantsTree);
/**
* Get the enum constants details tree.
*
* @param memberDetailsTree the content tree representing member details
* @return content tree for the enum constant details
*/
public Content getEnumConstantsDetails(Content memberDetailsTree);
/**
* Get the enum constants documentation.
*
* @param enumConstantsTree the content tree representing enum constants documentation
* @param isLastContent true if the content to be added is the last content
* @return content tree for the enum constants documentation
*/
public Content getEnumConstants(Content enumConstantsTree, boolean isLastContent);
/**
* Close the writer.
*/
public void close() throws IOException;
}

119
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/FieldWriter.java Normal file
View File

@@ -0,0 +1,119 @@
/*
* Copyright (c) 2003, 2012, 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 com.sun.tools.doclets.internal.toolkit;
import java.io.*;
import com.sun.javadoc.*;
/**
* The interface for writing field output.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public interface FieldWriter {
/**
* Get the field details tree header.
*
* @param classDoc the class being documented
* @param memberDetailsTree the content tree representing member details
* @return content tree for the field details header
*/
public Content getFieldDetailsTreeHeader(ClassDoc classDoc,
Content memberDetailsTree);
/**
* Get the field documentation tree header.
*
* @param field the constructor being documented
* @param fieldDetailsTree the content tree representing field details
* @return content tree for the field documentation header
*/
public Content getFieldDocTreeHeader(FieldDoc field,
Content fieldDetailsTree);
/**
* Get the signature for the given field.
*
* @param field the field being documented
* @return content tree for the field signature
*/
public Content getSignature(FieldDoc field);
/**
* Add the deprecated output for the given field.
*
* @param field the field being documented
* @param fieldDocTree content tree to which the deprecated information will be added
*/
public void addDeprecated(FieldDoc field, Content fieldDocTree);
/**
* Add the comments for the given field.
*
* @param field the field being documented
* @param fieldDocTree the content tree to which the comments will be added
*/
public void addComments(FieldDoc field, Content fieldDocTree);
/**
* Add the tags for the given field.
*
* @param field the field being documented
* @param fieldDocTree the content tree to which the tags will be added
*/
public void addTags(FieldDoc field, Content fieldDocTree);
/**
* Get the field details tree.
*
* @param memberDetailsTree the content tree representing member details
* @return content tree for the field details
*/
public Content getFieldDetails(Content memberDetailsTree);
/**
* Get the field documentation.
*
* @param fieldDocTree the content tree representing field documentation
* @param isLastContent true if the content to be added is the last content
* @return content tree for the field documentation
*/
public Content getFieldDoc(Content fieldDocTree, boolean isLastContent);
/**
* Close the writer.
*/
public void close() throws IOException;
}

119
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/MemberSummaryWriter.java Normal file
View File

@@ -0,0 +1,119 @@
/*
* Copyright (c) 2003, 2012, 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 com.sun.tools.doclets.internal.toolkit;
import java.io.*;
import java.util.*;
import com.sun.javadoc.*;
/**
* The interface for writing member summary output.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public interface MemberSummaryWriter {
/**
* Get the member summary header for the given class.
*
* @param classDoc the class the summary belongs to
* @param memberSummaryTree the content tree to which the member summary will be added
* @return a content tree for the member summary header
*/
public Content getMemberSummaryHeader(ClassDoc classDoc,
Content memberSummaryTree);
/**
* Get the summary table for the given class.
*
* @param classDoc the class the summary table belongs to
* @param tableContents list of contents that will be added to the summary table
* @return a content tree for the member summary table
*/
public Content getSummaryTableTree(ClassDoc classDoc,
List<Content> tableContents);
/**
* Add the member summary for the given class and member.
*
* @param classDoc the class the summary belongs to
* @param member the member that is documented
* @param firstSentenceTags the tags for the sentence being documented
* @param tableContents list of contents to which the summary will be added
* @param counter the counter for determining id and style for the table row
*/
public void addMemberSummary(ClassDoc classDoc, ProgramElementDoc member,
Tag[] firstSentenceTags, List<Content> tableContents, int counter);
/**
* Get the inherited member summary header for the given class.
*
* @param classDoc the class the summary belongs to
* @return a content tree containing the inherited summary header
*/
public Content getInheritedSummaryHeader(ClassDoc classDoc);
/**
* Add the inherited member summary for the given class and member.
*
* @param classDoc the class the inherited member belongs to
* @param member the inherited member that is being documented
* @param isFirst true if this is the first member in the list
* @param isLast true if this is the last member in the list
* @param linksTree the content tree to which the links will be added
*/
public void addInheritedMemberSummary(ClassDoc classDoc,
ProgramElementDoc member, boolean isFirst, boolean isLast,
Content linksTree);
/**
* Get inherited summary links.
*
* @return a content tree conatining the inherited summary links
*/
public Content getInheritedSummaryLinksTree();
/**
* Get the member tree.
*
* @param memberTree the content tree representating the member
* @return a content tree for the member
*/
public Content getMemberTree(Content memberTree);
/**
* Close the writer.
*/
public void close() throws IOException;
}

120
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/MethodWriter.java Normal file
View File

@@ -0,0 +1,120 @@
/*
* Copyright (c) 2003, 2012, 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 com.sun.tools.doclets.internal.toolkit;
import java.io.*;
import com.sun.javadoc.*;
/**
* The interface for writing method output.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public interface MethodWriter {
/**
* Get the method details tree header.
*
* @param classDoc the class being documented
* @param memberDetailsTree the content tree representing member details
* @return content tree for the method details header
*/
public Content getMethodDetailsTreeHeader(ClassDoc classDoc,
Content memberDetailsTree);
/**
* Get the method documentation tree header.
*
* @param method the method being documented
* @param methodDetailsTree the content tree representing method details
* @return content tree for the method documentation header
*/
public Content getMethodDocTreeHeader(MethodDoc method,
Content methodDetailsTree);
/**
* Get the signature for the given method.
*
* @param method the method being documented
* @return content tree for the method signature
*/
public Content getSignature(MethodDoc method);
/**
* Add the deprecated output for the given method.
*
* @param method the method being documented
* @param methodDocTree content tree to which the deprecated information will be added
*/
public void addDeprecated(MethodDoc method, Content methodDocTree);
/**
* Add the comments for the given method.
*
* @param holder the holder type (not erasure) of the method
* @param method the method being documented
* @param methodDocTree the content tree to which the comments will be added
*/
public void addComments(Type holder, MethodDoc method, Content methodDocTree);
/**
* Add the tags for the given method.
*
* @param method the method being documented
* @param methodDocTree the content tree to which the tags will be added
*/
public void addTags(MethodDoc method, Content methodDocTree);
/**
* Get the method details tree.
*
* @param methodDetailsTree the content tree representing method details
* @return content tree for the method details
*/
public Content getMethodDetails(Content methodDetailsTree);
/**
* Get the method documentation.
*
* @param methodDocTree the content tree representing method documentation
* @param isLastContent true if the content to be added is the last content
* @return content tree for the method documentation
*/
public Content getMethodDoc(Content methodDocTree, boolean isLastContent);
/**
* Close the writer.
*/
public void close() throws IOException;
}

49
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/NestedClassWriter.java Normal file
View File

@@ -0,0 +1,49 @@
/*
* Copyright (c) 2003, 2012, 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 com.sun.tools.doclets.internal.toolkit;
import java.io.*;
/**
* The interface for writing class output.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public interface NestedClassWriter {
/**
* Close the writer.
*/
public void close() throws IOException;
}

118
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/PackageSummaryWriter.java Normal file
View File

@@ -0,0 +1,118 @@
/*
* Copyright (c) 2003, 2012, 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 com.sun.tools.doclets.internal.toolkit;
import java.io.*;
import com.sun.javadoc.*;
/**
* The interface for writing package summary output.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public interface PackageSummaryWriter {
/**
* Get the header for the summary.
*
* @param heading Package name.
* @return the header to be added to the content tree
*/
public abstract Content getPackageHeader(String heading);
/**
* Get the header for the package content.
*
* @return a content tree for the package content header
*/
public abstract Content getContentHeader();
/**
* Get the header for the package summary.
*
* @return a content tree with the package summary header
*/
public abstract Content getSummaryHeader();
/**
* Adds the table of classes to the documentation tree.
*
* @param classes the array of classes to document.
* @param label the label for this table.
* @param tableSummary the summary string for the table
* @param tableHeader array of table headers
* @param summaryContentTree the content tree to which the summaries will be added
*/
public abstract void addClassesSummary(ClassDoc[] classes, String label,
String tableSummary, String[] tableHeader, Content summaryContentTree);
/**
* Adds the package description from the "packages.html" file to the documentation
* tree.
*
* @param packageContentTree the content tree to which the package description
* will be added
*/
public abstract void addPackageDescription(Content packageContentTree);
/**
* Adds the tag information from the "packages.html" file to the documentation
* tree.
*
* @param packageContentTree the content tree to which the package tags will
* be added
*/
public abstract void addPackageTags(Content packageContentTree);
/**
* Adds the footer to the documentation tree.
*
* @param contentTree the tree to which the footer will be added
*/
public abstract void addPackageFooter(Content contentTree);
/**
* Print the package summary document.
*
* @param contentTree the content tree that will be printed
*/
public abstract void printDocument(Content contentTree) throws IOException;
/**
* Close the writer.
*/
public abstract void close() throws IOException;
}

116
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/ProfilePackageSummaryWriter.java Normal file
View File

@@ -0,0 +1,116 @@
/*
* Copyright (c) 2013, 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 com.sun.tools.doclets.internal.toolkit;
import java.io.*;
import com.sun.javadoc.*;
/**
* The interface for writing profile package summary output.
*
* <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 Bhavesh Patel
*/
public interface ProfilePackageSummaryWriter {
/**
* Get the header for the summary.
*
* @param heading Package name.
* @return the header to be added to the content tree
*/
public abstract Content getPackageHeader(String heading);
/**
* Get the header for the content.
*
* @return a content tree for the content header
*/
public abstract Content getContentHeader();
/**
* Get the header for the package summary.
*
* @return a content tree with the package summary header
*/
public abstract Content getSummaryHeader();
/**
* Adds the table of classes to the documentation tree.
*
* @param classes the array of classes to document.
* @param label the label for this table.
* @param tableSummary the summary string for the table
* @param tableHeader array of table headers
* @param summaryContentTree the content tree to which the summaries will be added
*/
public abstract void addClassesSummary(ClassDoc[] classes, String label,
String tableSummary, String[] tableHeader, Content summaryContentTree);
/**
* Adds the package description from the "packages.html" file to the documentation
* tree.
*
* @param packageContentTree the content tree to which the package description
* will be added
*/
public abstract void addPackageDescription(Content packageContentTree);
/**
* Adds the tag information from the "packages.html" file to the documentation
* tree.
*
* @param packageContentTree the content tree to which the package tags will
* be added
*/
public abstract void addPackageTags(Content packageContentTree);
/**
* Adds the footer to the documentation tree.
*
* @param contentTree the tree to which the footer will be added
*/
public abstract void addPackageFooter(Content contentTree);
/**
* Print the package summary document.
*
* @param contentTree the content tree that will be printed
*/
public abstract void printDocument(Content contentTree) throws IOException;
/**
* Close the writer.
*/
public abstract void close() throws IOException;
}

120
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/ProfileSummaryWriter.java Normal file
View File

@@ -0,0 +1,120 @@
/*
* Copyright (c) 2013, 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 com.sun.tools.doclets.internal.toolkit;
import java.io.*;
import com.sun.javadoc.*;
/**
* The interface for writing profile summary output.
*
* <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 Bhavesh Patel
*/
public interface ProfileSummaryWriter {
/**
* Get the header for the summary.
*
* @param heading profile name.
* @return the header to be added to the content tree
*/
public abstract Content getProfileHeader(String heading);
/**
* Get the header for the profile content.
*
* @return a content tree for the profile content header
*/
public abstract Content getContentHeader();
/**
* Get the header for the summary header.
*
* @return a content tree with the summary header
*/
public abstract Content getSummaryHeader();
/**
* Get the header for the summary tree.
*
* @param summaryContentTree the content tree.
* @return a content tree with the summary tree
*/
public abstract Content getSummaryTree(Content summaryContentTree);
/**
* Get the header for the package summary header.
*
* @return a content tree with the package summary header
*/
public abstract Content getPackageSummaryHeader(PackageDoc pkg);
/**
* Get the header for the package summary tree.
*
* @return a content tree with the package summary
*/
public abstract Content getPackageSummaryTree(Content packageSummaryContentTree);
/**
* Adds the table of classes to the documentation tree.
*
* @param classes the array of classes to document.
* @param label the label for this table.
* @param tableSummary the summary string for the table
* @param tableHeader array of table headers
* @param packageSummaryContentTree the content tree to which the summaries will be added
*/
public abstract void addClassesSummary(ClassDoc[] classes, String label,
String tableSummary, String[] tableHeader, Content packageSummaryContentTree);
/**
* Adds the footer to the documentation tree.
*
* @param contentTree the tree to which the footer will be added
*/
public abstract void addProfileFooter(Content contentTree);
/**
* Print the profile summary document.
*
* @param contentTree the content tree that will be printed
*/
public abstract void printDocument(Content contentTree) throws IOException;
/**
* Close the writer.
*/
public abstract void close() throws IOException;
}

119
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/PropertyWriter.java Normal file
View File

@@ -0,0 +1,119 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit;
import java.io.*;
import com.sun.javadoc.*;
/**
* The interface for writing property output.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.7
*/
public interface PropertyWriter {
/**
* Get the property details tree header.
*
* @param classDoc the class being documented
* @param memberDetailsTree the content tree representing member details
* @return content tree for the property details header
*/
public Content getPropertyDetailsTreeHeader(ClassDoc classDoc,
Content memberDetailsTree);
/**
* Get the property documentation tree header.
*
* @param property the property being documented
* @param propertyDetailsTree the content tree representing property details
* @return content tree for the property documentation header
*/
public Content getPropertyDocTreeHeader(MethodDoc property,
Content propertyDetailsTree);
/**
* Get the signature for the given property.
*
* @param property the property being documented
* @return content tree for the property signature
*/
public Content getSignature(MethodDoc property);
/**
* Add the deprecated output for the given property.
*
* @param property the property being documented
* @param propertyDocTree content tree to which the deprecated information will be added
*/
public void addDeprecated(MethodDoc property, Content propertyDocTree);
/**
* Add the comments for the given property.
*
* @param property the property being documented
* @param propertyDocTree the content tree to which the comments will be added
*/
public void addComments(MethodDoc property, Content propertyDocTree);
/**
* Add the tags for the given property.
*
* @param property the property being documented
* @param propertyDocTree the content tree to which the tags will be added
*/
public void addTags(MethodDoc property, Content propertyDocTree);
/**
* Get the property details tree.
*
* @param memberDetailsTree the content tree representing member details
* @return content tree for the property details
*/
public Content getPropertyDetails(Content memberDetailsTree);
/**
* Get the property documentation.
*
* @param propertyDocTree the content tree representing property documentation
* @param isLastContent true if the content to be added is the last content
* @return content tree for the property documentation
*/
public Content getPropertyDoc(Content propertyDocTree, boolean isLastContent);
/**
* Close the writer.
*/
public void close() throws IOException;
}

314
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/SerializedFormWriter.java Normal file
View File

@@ -0,0 +1,314 @@
/*
* Copyright (c) 2003, 2012, 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 com.sun.tools.doclets.internal.toolkit;
import java.io.*;
import com.sun.javadoc.*;
/**
* The interface for writing serialized form output.
*
* <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
* @since 1.5
*/
public interface SerializedFormWriter {
/**
* Get the header.
*
* @param header the header to write.
* @return the header content tree
*/
public Content getHeader(String header);
/**
* Get the serialized form summaries header.
*
* @return the serialized form summary header tree
*/
public Content getSerializedSummariesHeader();
/**
* Get the package serialized form header.
*
* @return the package serialized form header tree
*/
public Content getPackageSerializedHeader();
/**
* Get the given package header.
*
* @param packageName the package header to write
* @return a content tree for the package header
*/
public Content getPackageHeader(String packageName);
/**
* Get the serialized class header.
*
* @return a content tree for the serialized class header
*/
public Content getClassSerializedHeader();
/**
* Get the heading for the serializable class.
*
* @param classDoc the class being processed
* @return a content tree for the class heading
*/
public Content getClassHeader(ClassDoc classDoc);
/**
* Get the serial UID info header.
*
* @return a content tree for the serial uid info header
*/
public Content getSerialUIDInfoHeader();
/**
* Adds the serial UID info.
*
* @param header the header that will show up before the UID.
* @param serialUID the serial UID to print.
* @param serialUidTree the serial UID tree to which the content will be added.
*/
public void addSerialUIDInfo(String header, String serialUID,
Content serialUidTree);
/**
* Get the class serialize content header.
*
* @return a content tree for the class serialize content header
*/
public Content getClassContentHeader();
/**
* Return an instance of a SerialFieldWriter.
*
* @return an instance of a SerialFieldWriter.
*/
public SerialFieldWriter getSerialFieldWriter(ClassDoc classDoc);
/**
* Return an instance of a SerialMethodWriter.
*
* @return an instance of a SerialMethodWriter.
*/
public SerialMethodWriter getSerialMethodWriter(ClassDoc classDoc);
/**
* Close the writer.
*/
public abstract void close() throws IOException;
/**
* Get the serialized content.
*
* @param serializedTreeContent content for serialized data
* @return a content tree for serialized information
*/
public Content getSerializedContent(Content serializedTreeContent);
/**
* Add the footer.
*
* @param serializedTree the serialized tree to be added
*/
public void addFooter(Content serializedTree);
/**
* Print the serialized form document.
*
* @param serializedTree the content tree that will be printed
*/
public abstract void printDocument(Content serializedTree) throws IOException;
/**
* Write the serialized form for a given field.
*/
public interface SerialFieldWriter {
/**
* Get the serializable field header.
*
* @return serialized fields header content tree
*/
public Content getSerializableFieldsHeader();
/**
* Get the field content header.
*
* @param isLastContent true if this is the last content to be documented
* @return fields header content tree
*/
public Content getFieldsContentHeader(boolean isLastContent);
/**
* Get the fields content.
*
* @param heading the heading to write.
* @param contentTree content tree to which the heading will be added
* @return serializable fields content tree
*/
public Content getSerializableFields(String heading, Content contentTree);
/**
* Adds the deprecated information for this member.
*
* @param field the field to document.
* @param contentTree content tree to which the deprecated information will be added
*/
public void addMemberDeprecatedInfo(FieldDoc field, Content contentTree);
/**
* Adds the description text for this member.
*
* @param field the field to document.
* @param contentTree content tree to which the member description will be added
*/
public void addMemberDescription(FieldDoc field, Content contentTree);
/**
* Adds the description text for this member represented by the tag.
*
* @param serialFieldTag the field to document (represented by tag).
* @param contentTree content tree to which the member description will be added
*/
public void addMemberDescription(SerialFieldTag serialFieldTag, Content contentTree);
/**
* Adds the tag information for this member.
*
* @param field the field to document.
* @param contentTree content tree to which the member tags will be added
*/
public void addMemberTags(FieldDoc field, Content contentTree);
/**
* Adds the member header.
*
* @param fieldType the type of the field.
* @param fieldTypeStr the type of the field in string format. We will
* print this out if we can't link to the type.
* @param fieldDimensions the dimensions of the field.
* @param fieldName the name of the field.
* @param contentTree content tree to which the member header will be added
*/
public void addMemberHeader(ClassDoc fieldType, String fieldTypeStr,
String fieldDimensions, String fieldName, Content contentTree);
/**
* Check to see if overview details should be printed. If
* nocomment option set or if there is no text to be printed
* for deprecation info, inline comment or tags,
* do not print overview details.
*
* @param field the field to check overview details for.
* @return true if overview details need to be printed
*/
public boolean shouldPrintOverview(FieldDoc field);
}
/**
* Write the serialized form for a given field.
*/
public interface SerialMethodWriter {
/**
* Get the serializable method header.
*
* @return serializable methods content tree
*/
public Content getSerializableMethodsHeader();
/**
* Get the method content header.
*
* @param isLastContent true if this is the last content to be documented
* @return methods content tree
*/
public Content getMethodsContentHeader(boolean isLastContent);
/**
* Write the given heading.
*
* @param heading the heading to write
* @param serializableMethodTree content tree which will be added
* @return serializable methods content tree
*/
public Content getSerializableMethods(String heading, Content serializableMethodTree);
/**
* Write a warning that no serializable methods exist.
*
* @param msg the warning to print
* @return no customization message tree
*/
public Content getNoCustomizationMsg(String msg);
/**
* Adds the header.
*
* @param member the member to write the header for
* @param methodsContentTree content tree to which the header will be added
*/
public void addMemberHeader(MethodDoc member, Content methodsContentTree);
/**
* Adds the deprecated information for this member.
*
* @param member the member to write the deprecated information for
* @param methodsContentTree content tree to which the deprecated
* information will be added
*/
public void addDeprecatedMemberInfo(MethodDoc member, Content methodsContentTree);
/**
* Adds the description for this member.
*
* @param member the member to write the information for
* @param methodsContentTree content tree to which the member
* information will be added
*/
public void addMemberDescription(MethodDoc member, Content methodsContentTree);
/**
* Adds the tag information for this member.
*
* @param member the member to write the tags information for
* @param methodsContentTree content tree to which the tags
* information will be added
*/
public void addMemberTags(MethodDoc member, Content methodsContentTree);
}
}

249
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/WriterFactory.java Normal file
View File

@@ -0,0 +1,249 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit;
import com.sun.javadoc.*;
import com.sun.tools.javac.jvm.Profile;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* The interface for a factory creates writers.
*
* <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
* @since 1.4
*/
public interface WriterFactory {
/**
* Return the writer for the constant summary.
*
* @return the writer for the constant summary. Return null if this
* writer is not supported by the doclet.
*/
public abstract ConstantsSummaryWriter getConstantsSummaryWriter()
throws Exception;
/**
* Return the writer for the package summary.
*
* @param packageDoc the package being documented.
* @param prevPkg the previous package that was documented.
* @param nextPkg the next package being documented.
* @return the writer for the package summary. Return null if this
* writer is not supported by the doclet.
*/
public abstract PackageSummaryWriter getPackageSummaryWriter(PackageDoc
packageDoc, PackageDoc prevPkg, PackageDoc nextPkg)
throws Exception;
/**
* Return the writer for the profile summary.
*
* @param profile the profile being documented.
* @param prevProfile the previous profile that was documented.
* @param nextProfile the next profile being documented.
* @return the writer for the profile summary. Return null if this
* writer is not supported by the doclet.
*/
public abstract ProfileSummaryWriter getProfileSummaryWriter(Profile
profile, Profile prevProfile, Profile nextProfile)
throws Exception;
/**
* Return the writer for the profile package summary.
*
* @param packageDoc the profile package being documented.
* @param prevPkg the previous profile package that was documented.
* @param nextPkg the next profile package being documented.
* @param profile the profile being documented.
* @return the writer for the profile package summary. Return null if this
* writer is not supported by the doclet.
*/
public abstract ProfilePackageSummaryWriter getProfilePackageSummaryWriter(
PackageDoc packageDoc, PackageDoc prevPkg, PackageDoc nextPkg,
Profile profile) throws Exception;
/**
* Return the writer for a class.
*
* @param classDoc the class being documented.
* @param prevClass the previous class that was documented.
* @param nextClass the next class being documented.
* @param classTree the class tree.
* @return the writer for the class. Return null if this
* writer is not supported by the doclet.
*/
public abstract ClassWriter getClassWriter(ClassDoc classDoc,
ClassDoc prevClass, ClassDoc nextClass, ClassTree classTree)
throws Exception;
/**
* Return the writer for an annotation type.
*
* @param annotationType the type being documented.
* @param prevType the previous type that was documented.
* @param nextType the next type being documented.
* @return the writer for the annotation type. Return null if this
* writer is not supported by the doclet.
*/
public abstract AnnotationTypeWriter getAnnotationTypeWriter(
AnnotationTypeDoc annotationType, Type prevType, Type nextType)
throws Exception;
/**
* Return the method writer for a given class.
*
* @param classWriter the writer for the class being documented.
* @return the method writer for the give class. Return null if this
* writer is not supported by the doclet.
*/
public abstract MethodWriter getMethodWriter(ClassWriter classWriter)
throws Exception;
/**
* Return the annotation type field writer for a given annotation type.
*
* @param annotationTypeWriter the writer for the annotation type
* being documented.
* @return the member writer for the given annotation type. Return null if
* this writer is not supported by the doclet.
*/
public abstract AnnotationTypeFieldWriter
getAnnotationTypeFieldWriter(
AnnotationTypeWriter annotationTypeWriter) throws Exception;
/**
* Return the annotation type optional member writer for a given annotation
* type.
*
* @param annotationTypeWriter the writer for the annotation type
* being documented.
* @return the member writer for the given annotation type. Return null if
* this writer is not supported by the doclet.
*/
public abstract AnnotationTypeOptionalMemberWriter
getAnnotationTypeOptionalMemberWriter(
AnnotationTypeWriter annotationTypeWriter) throws Exception;
/**
* Return the annotation type required member writer for a given annotation type.
*
* @param annotationTypeWriter the writer for the annotation type
* being documented.
* @return the member writer for the given annotation type. Return null if
* this writer is not supported by the doclet.
*/
public abstract AnnotationTypeRequiredMemberWriter
getAnnotationTypeRequiredMemberWriter(
AnnotationTypeWriter annotationTypeWriter) throws Exception;
/**
* Return the enum constant writer for a given class.
*
* @param classWriter the writer for the class being documented.
* @return the enum constant writer for the give class. Return null if this
* writer is not supported by the doclet.
*/
public abstract EnumConstantWriter getEnumConstantWriter(
ClassWriter classWriter) throws Exception;
/**
* Return the field writer for a given class.
*
* @param classWriter the writer for the class being documented.
* @return the field writer for the give class. Return null if this
* writer is not supported by the doclet.
*/
public abstract FieldWriter getFieldWriter(ClassWriter classWriter)
throws Exception;
/**
* Return the property writer for a given class.
*
* @param classWriter the writer for the class being documented.
* @return the property writer for the give class. Return null if this
* writer is not supported by the doclet.
*/
public abstract PropertyWriter getPropertyWriter(ClassWriter classWriter)
throws Exception;
/**
* Return the constructor writer for a given class.
*
* @param classWriter the writer for the class being documented.
* @return the method writer for the give class. Return null if this
* writer is not supported by the doclet.
*/
public abstract ConstructorWriter getConstructorWriter(
ClassWriter classWriter)
throws Exception;
/**
* Return the specified member summary writer for a given class.
*
* @param classWriter the writer for the class being documented.
* @param memberType the {@link VisibleMemberMap} member type indicating
* the type of member summary that should be returned.
* @return the summary writer for the give class. Return null if this
* writer is not supported by the doclet.
*
* @see VisibleMemberMap
* @throws IllegalArgumentException if memberType is unknown.
*/
public abstract MemberSummaryWriter getMemberSummaryWriter(
ClassWriter classWriter, int memberType)
throws Exception;
/**
* Return the specified member summary writer for a given annotation type.
*
* @param annotationTypeWriter the writer for the annotation type being
* documented.
* @param memberType the {@link VisibleMemberMap} member type indicating
* the type of member summary that should be returned.
* @return the summary writer for the give class. Return null if this
* writer is not supported by the doclet.
*
* @see VisibleMemberMap
* @throws IllegalArgumentException if memberType is unknown.
*/
public abstract MemberSummaryWriter getMemberSummaryWriter(
AnnotationTypeWriter annotationTypeWriter, int memberType)
throws Exception;
/**
* Return the writer for the serialized form.
*
* @return the writer for the serialized form.
*/
public SerializedFormWriter getSerializedFormWriter() throws Exception;
}

189
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/AbstractBuilder.java Normal file
View File

@@ -0,0 +1,189 @@
/*
* Copyright (c) 2003, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.io.*;
import java.lang.reflect.*;
import java.util.*;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* The superclass for all builders. A builder is a class that provides
* the structure and content of API documentation. A builder is completely
* doclet independent which means that any doclet can use builders to
* construct documentation, as long as it impelements the appropriate
* writer interfaces. For example, if a doclet wanted to use
* {@link ConstantsSummaryBuilder} to build a constant summary, all it has to
* do is implement the ConstantsSummaryWriter interface and pass it to the
* builder using a WriterFactory.
*
* <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
* @since 1.5
*/
public abstract class AbstractBuilder {
public static class Context {
/**
* The configuration used in this run of the doclet.
*/
final Configuration configuration;
/**
* Keep track of which packages we have seen for
* efficiency purposes. We don't want to copy the
* doc files multiple times for a single package.
*/
final Set<String> containingPackagesSeen;
/**
* Shared parser for the builder XML file
*/
final LayoutParser layoutParser;
Context(Configuration configuration,
Set<String> containingPackagesSeen,
LayoutParser layoutParser) {
this.configuration = configuration;
this.containingPackagesSeen = containingPackagesSeen;
this.layoutParser = layoutParser;
}
}
/**
* The configuration used in this run of the doclet.
*/
protected final Configuration configuration;
/**
* Keep track of which packages we have seen for
* efficiency purposes. We don't want to copy the
* doc files multiple times for a single package.
*/
protected final Set<String> containingPackagesSeen;
protected final LayoutParser layoutParser;
/**
* True if we want to print debug output.
*/
protected static final boolean DEBUG = false;
/**
* Construct a Builder.
* @param configuration the configuration used in this run
* of the doclet.
*/
public AbstractBuilder(Context c) {
this.configuration = c.configuration;
this.containingPackagesSeen = c.containingPackagesSeen;
this.layoutParser = c.layoutParser;
}
/**
* Return the name of this builder.
*
* @return the name of the builder.
*/
public abstract String getName();
/**
* Build the documentation.
*
* @throws IOException there was a problem writing the output.
*/
public abstract void build() throws IOException;
/**
* Build the documentation, as specified by the given XML element.
*
* @param node the XML element that specifies which component to document.
* @param contentTree content tree to which the documentation will be added
*/
protected void build(XMLNode node, Content contentTree) {
String component = node.name;
try {
invokeMethod("build" + component,
new Class<?>[]{XMLNode.class, Content.class},
new Object[]{node, contentTree});
} catch (NoSuchMethodException e) {
e.printStackTrace();
configuration.root.printError("Unknown element: " + component);
throw new DocletAbortException(e);
} catch (InvocationTargetException e) {
Throwable cause = e.getCause();
if (cause instanceof FatalError) {
throw (FatalError) cause;
} else if (cause instanceof DocletAbortException) {
throw (DocletAbortException) cause;
} else {
throw new DocletAbortException(cause);
}
} catch (Exception e) {
e.printStackTrace();
configuration.root.printError("Exception " +
e.getClass().getName() +
" thrown while processing element: " + component);
throw new DocletAbortException(e);
}
}
/**
* Build the documentation, as specified by the children of the given XML element.
*
* @param node the XML element that specifies which components to document.
* @param contentTree content tree to which the documentation will be added
*/
protected void buildChildren(XMLNode node, Content contentTree) {
for (XMLNode child : node.children)
build(child, contentTree);
}
/**
* Given the name and parameters, invoke the method in the builder. This
* method is required to invoke the appropriate build method as instructed
* by the builder XML file.
*
* @param methodName the name of the method that we would like to invoke.
* @param paramClasses the types for each parameter.
* @param params the parameters of the method.
*/
protected void invokeMethod(String methodName, Class<?>[] paramClasses,
Object[] params)
throws Exception {
if (DEBUG) {
configuration.root.printError("DEBUG: " + this.getClass().getName() + "." + methodName);
}
Method method = this.getClass().getMethod(methodName, paramClasses);
method.invoke(this, params);
}
}

88
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/AbstractMemberBuilder.java Normal file
View File

@@ -0,0 +1,88 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.util.Set;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* The superclass for all member builders. Member builders are only executed
* within Class Builders. They essentially build sub-components. For example,
* method documentation is a sub-component of class documentation.
*
* <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
* @since 1.5
*/
public abstract class AbstractMemberBuilder extends AbstractBuilder {
/**
* Construct a SubBuilder.
* @param configuration the configuration used in this run
* of the doclet.
*/
public AbstractMemberBuilder(Context context) {
super(context);
}
/**
* This method is not supported by sub-builders.
*
* @throws DocletAbortException this method will always throw a
* DocletAbortException because it is not supported.
*/
public void build() throws DocletAbortException {
//You may not call the build method in a subbuilder.
throw new DocletAbortException("not supported");
}
/**
* Build the sub component if there is anything to document.
*
* @param node the XML element that specifies which components to document.
* @param contentTree content tree to which the documentation will be added
*/
@Override
public void build(XMLNode node, Content contentTree) {
if (hasMembersToDocument()) {
super.build(node, contentTree);
}
}
/**
* Return true if this subbuilder has anything to document.
*
* @return true if this subbuilder has anything to document.
*/
public abstract boolean hasMembersToDocument();
}

265
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/AnnotationTypeBuilder.java Normal file
View File

@@ -0,0 +1,265 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.io.*;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* Builds the summary for a given annotation type.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public class AnnotationTypeBuilder extends AbstractBuilder {
/**
* The root element of the annotation type XML is {@value}.
*/
public static final String ROOT = "AnnotationTypeDoc";
/**
* The annotation type being documented.
*/
private final AnnotationTypeDoc annotationTypeDoc;
/**
* The doclet specific writer.
*/
private final AnnotationTypeWriter writer;
/**
* The content tree for the annotation documentation.
*/
private Content contentTree;
/**
* Construct a new ClassBuilder.
*
* @param context the build context.
* @param annotationTypeDoc the class being documented.
* @param writer the doclet specific writer.
*/
private AnnotationTypeBuilder(Context context,
AnnotationTypeDoc annotationTypeDoc,
AnnotationTypeWriter writer) {
super(context);
this.annotationTypeDoc = annotationTypeDoc;
this.writer = writer;
}
/**
* Construct a new ClassBuilder.
*
* @param context the build context.
* @param annotationTypeDoc the class being documented.
* @param writer the doclet specific writer.
*/
public static AnnotationTypeBuilder getInstance(Context context,
AnnotationTypeDoc annotationTypeDoc,
AnnotationTypeWriter writer)
throws Exception {
return new AnnotationTypeBuilder(context, annotationTypeDoc, writer);
}
/**
* {@inheritDoc}
*/
public void build() throws IOException {
build(layoutParser.parseXML(ROOT), contentTree);
}
/**
* {@inheritDoc}
*/
public String getName() {
return ROOT;
}
/**
* Build the annotation type documentation.
*
* @param node the XML element that specifies which components to document
* @param contentTree the content tree to which the documentation will be added
*/
public void buildAnnotationTypeDoc(XMLNode node, Content contentTree) throws Exception {
contentTree = writer.getHeader(configuration.getText("doclet.AnnotationType") +
" " + annotationTypeDoc.name());
Content annotationContentTree = writer.getAnnotationContentHeader();
buildChildren(node, annotationContentTree);
contentTree.addContent(annotationContentTree);
writer.addFooter(contentTree);
writer.printDocument(contentTree);
writer.close();
copyDocFiles();
}
/**
* Copy the doc files for the current ClassDoc if necessary.
*/
private void copyDocFiles() {
PackageDoc containingPackage = annotationTypeDoc.containingPackage();
if((configuration.packages == null ||
Arrays.binarySearch(configuration.packages,
containingPackage) < 0) &&
! containingPackagesSeen.contains(containingPackage.name())){
//Only copy doc files dir if the containing package is not
//documented AND if we have not documented a class from the same
//package already. Otherwise, we are making duplicate copies.
Util.copyDocFiles(configuration, containingPackage);
containingPackagesSeen.add(containingPackage.name());
}
}
/**
* Build the annotation information tree documentation.
*
* @param node the XML element that specifies which components to document
* @param annotationContentTree the content tree to which the documentation will be added
*/
public void buildAnnotationTypeInfo(XMLNode node, Content annotationContentTree) {
Content annotationInfoTree = writer.getAnnotationInfoTreeHeader();
buildChildren(node, annotationInfoTree);
annotationContentTree.addContent(writer.getAnnotationInfo(annotationInfoTree));
}
/**
* If this annotation is deprecated, build the appropriate information.
*
* @param node the XML element that specifies which components to document
* @param annotationInfoTree the content tree to which the documentation will be added
*/
public void buildDeprecationInfo (XMLNode node, Content annotationInfoTree) {
writer.addAnnotationTypeDeprecationInfo(annotationInfoTree);
}
/**
* Build the signature of the current annotation type.
*
* @param node the XML element that specifies which components to document
* @param annotationInfoTree the content tree to which the documentation will be added
*/
public void buildAnnotationTypeSignature(XMLNode node, Content annotationInfoTree) {
StringBuilder modifiers = new StringBuilder(
annotationTypeDoc.modifiers() + " ");
writer.addAnnotationTypeSignature(Util.replaceText(
modifiers.toString(), "interface", "@interface"), annotationInfoTree);
}
/**
* Build the annotation type description.
*
* @param node the XML element that specifies which components to document
* @param annotationInfoTree the content tree to which the documentation will be added
*/
public void buildAnnotationTypeDescription(XMLNode node, Content annotationInfoTree) {
writer.addAnnotationTypeDescription(annotationInfoTree);
}
/**
* Build the tag information for the current annotation type.
*
* @param node the XML element that specifies which components to document
* @param annotationInfoTree the content tree to which the documentation will be added
*/
public void buildAnnotationTypeTagInfo(XMLNode node, Content annotationInfoTree) {
writer.addAnnotationTypeTagInfo(annotationInfoTree);
}
/**
* Build the member summary contents of the page.
*
* @param node the XML element that specifies which components to document
* @param annotationContentTree the content tree to which the documentation will be added
*/
public void buildMemberSummary(XMLNode node, Content annotationContentTree)
throws Exception {
Content memberSummaryTree = writer.getMemberTreeHeader();
configuration.getBuilderFactory().
getMemberSummaryBuilder(writer).buildChildren(node, memberSummaryTree);
annotationContentTree.addContent(writer.getMemberSummaryTree(memberSummaryTree));
}
/**
* Build the member details contents of the page.
*
* @param node the XML element that specifies which components to document
* @param annotationContentTree the content tree to which the documentation will be added
*/
public void buildAnnotationTypeMemberDetails(XMLNode node, Content annotationContentTree) {
Content memberDetailsTree = writer.getMemberTreeHeader();
buildChildren(node, memberDetailsTree);
if (memberDetailsTree.isValid()) {
annotationContentTree.addContent(writer.getMemberDetailsTree(memberDetailsTree));
}
}
/**
* Build the annotation type field documentation.
*
* @param node the XML element that specifies which components to document
* @param memberDetailsTree the content tree to which the documentation will be added
*/
public void buildAnnotationTypeFieldDetails(XMLNode node, Content memberDetailsTree)
throws Exception {
configuration.getBuilderFactory().
getAnnotationTypeFieldsBuilder(writer).buildChildren(node, memberDetailsTree);
}
/**
* Build the annotation type optional member documentation.
*
* @param node the XML element that specifies which components to document
* @param memberDetailsTree the content tree to which the documentation will be added
*/
public void buildAnnotationTypeOptionalMemberDetails(XMLNode node, Content memberDetailsTree)
throws Exception {
configuration.getBuilderFactory().
getAnnotationTypeOptionalMemberBuilder(writer).buildChildren(node, memberDetailsTree);
}
/**
* Build the annotation type required member documentation.
*
* @param node the XML element that specifies which components to document
* @param memberDetailsTree the content tree to which the documentation will be added
*/
public void buildAnnotationTypeRequiredMemberDetails(XMLNode node, Content memberDetailsTree)
throws Exception {
configuration.getBuilderFactory().
getAnnotationTypeRequiredMemberBuilder(writer).buildChildren(node, memberDetailsTree);
}
}

240
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/AnnotationTypeFieldBuilder.java Normal file
View File

@@ -0,0 +1,240 @@
/*
* Copyright (c) 2013, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* Builds documentation for annotation type fields.
*
* <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 Bhavesh Patel
* @since 1.8
*/
public class AnnotationTypeFieldBuilder extends AbstractMemberBuilder {
/**
* The annotation type whose members are being documented.
*/
protected ClassDoc classDoc;
/**
* The visible members for the given class.
*/
protected VisibleMemberMap visibleMemberMap;
/**
* The writer to output the member documentation.
*/
protected AnnotationTypeFieldWriter writer;
/**
* The list of members being documented.
*/
protected List<ProgramElementDoc> members;
/**
* The index of the current member that is being documented at this point
* in time.
*/
protected int currentMemberIndex;
/**
* Construct a new AnnotationTypeFieldsBuilder.
*
* @param context the build context.
* @param classDoc the class whose members are being documented.
* @param writer the doclet specific writer.
* @param memberType the type of member that is being documented.
*/
protected AnnotationTypeFieldBuilder(Context context,
ClassDoc classDoc,
AnnotationTypeFieldWriter writer,
int memberType) {
super(context);
this.classDoc = classDoc;
this.writer = writer;
this.visibleMemberMap = new VisibleMemberMap(classDoc, memberType,
configuration);
this.members = new ArrayList<ProgramElementDoc>(
this.visibleMemberMap.getMembersFor(classDoc));
if (configuration.getMemberComparator() != null) {
Collections.sort(this.members, configuration.getMemberComparator());
}
}
/**
* Construct a new AnnotationTypeFieldBuilder.
*
* @param context the build context.
* @param classDoc the class whose members are being documented.
* @param writer the doclet specific writer.
*/
public static AnnotationTypeFieldBuilder getInstance(
Context context, ClassDoc classDoc,
AnnotationTypeFieldWriter writer) {
return new AnnotationTypeFieldBuilder(context, classDoc,
writer, VisibleMemberMap.ANNOTATION_TYPE_FIELDS);
}
/**
* {@inheritDoc}
*/
public String getName() {
return "AnnotationTypeFieldDetails";
}
/**
* Returns a list of members that will be documented for the given class.
* This information can be used for doclet specific documentation
* generation.
*
* @param classDoc the {@link ClassDoc} we want to check.
* @return a list of members that will be documented.
*/
public List<ProgramElementDoc> members(ClassDoc classDoc) {
return visibleMemberMap.getMembersFor(classDoc);
}
/**
* Returns the visible member map for the members of this class.
*
* @return the visible member map for the members of this class.
*/
public VisibleMemberMap getVisibleMemberMap() {
return visibleMemberMap;
}
/**
* summaryOrder.size()
*/
public boolean hasMembersToDocument() {
return members.size() > 0;
}
/**
* Build the annotation type field documentation.
*
* @param node the XML element that specifies which components to document
* @param memberDetailsTree the content tree to which the documentation will be added
*/
public void buildAnnotationTypeField(XMLNode node, Content memberDetailsTree) {
buildAnnotationTypeMember(node, memberDetailsTree);
}
/**
* Build the member documentation.
*
* @param node the XML element that specifies which components to document
* @param memberDetailsTree the content tree to which the documentation will be added
*/
public void buildAnnotationTypeMember(XMLNode node, Content memberDetailsTree) {
if (writer == null) {
return;
}
int size = members.size();
if (size > 0) {
writer.addAnnotationFieldDetailsMarker(memberDetailsTree);
for (currentMemberIndex = 0; currentMemberIndex < size;
currentMemberIndex++) {
Content detailsTree = writer.getMemberTreeHeader();
writer.addAnnotationDetailsTreeHeader(classDoc, detailsTree);
Content annotationDocTree = writer.getAnnotationDocTreeHeader(
(MemberDoc) members.get(currentMemberIndex),
detailsTree);
buildChildren(node, annotationDocTree);
detailsTree.addContent(writer.getAnnotationDoc(
annotationDocTree, (currentMemberIndex == size - 1)));
memberDetailsTree.addContent(writer.getAnnotationDetails(detailsTree));
}
}
}
/**
* Build the signature.
*
* @param node the XML element that specifies which components to document
* @param annotationDocTree the content tree to which the documentation will be added
*/
public void buildSignature(XMLNode node, Content annotationDocTree) {
annotationDocTree.addContent(
writer.getSignature((MemberDoc) members.get(currentMemberIndex)));
}
/**
* Build the deprecation information.
*
* @param node the XML element that specifies which components to document
* @param annotationDocTree the content tree to which the documentation will be added
*/
public void buildDeprecationInfo(XMLNode node, Content annotationDocTree) {
writer.addDeprecated((MemberDoc) members.get(currentMemberIndex),
annotationDocTree);
}
/**
* Build the comments for the member. Do nothing if
* {@link Configuration#nocomment} is set to true.
*
* @param node the XML element that specifies which components to document
* @param annotationDocTree the content tree to which the documentation will be added
*/
public void buildMemberComments(XMLNode node, Content annotationDocTree) {
if(! configuration.nocomment){
writer.addComments((MemberDoc) members.get(currentMemberIndex),
annotationDocTree);
}
}
/**
* Build the tag information.
*
* @param node the XML element that specifies which components to document
* @param annotationDocTree the content tree to which the documentation will be added
*/
public void buildTagInfo(XMLNode node, Content annotationDocTree) {
writer.addTags((MemberDoc) members.get(currentMemberIndex),
annotationDocTree);
}
/**
* Return the annotation type field writer for this builder.
*
* @return the annotation type field writer for this builder.
*/
public AnnotationTypeFieldWriter getWriter() {
return writer;
}
}

114
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/AnnotationTypeOptionalMemberBuilder.java Normal file
View File

@@ -0,0 +1,114 @@
/*
* Copyright (c) 2003, 2012, 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 com.sun.tools.doclets.internal.toolkit.builders;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* Builds documentation for optional annotation type members.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public class AnnotationTypeOptionalMemberBuilder extends
AnnotationTypeRequiredMemberBuilder {
/**
* Construct a new AnnotationTypeMemberBuilder.
*
* @param context the build context.
* @param classDoc the class whose members are being documented.
* @param writer the doclet specific writer.
*/
private AnnotationTypeOptionalMemberBuilder(Context context,
ClassDoc classDoc,
AnnotationTypeOptionalMemberWriter writer) {
super(context, classDoc, writer,
VisibleMemberMap.ANNOTATION_TYPE_MEMBER_OPTIONAL);
}
/**
* Construct a new AnnotationTypeMemberBuilder.
*
* @param context the build context.
* @param classDoc the class whose members are being documented.
* @param writer the doclet specific writer.
*/
public static AnnotationTypeOptionalMemberBuilder getInstance(
Context context, ClassDoc classDoc,
AnnotationTypeOptionalMemberWriter writer) {
return new AnnotationTypeOptionalMemberBuilder(context,
classDoc, writer);
}
/**
* {@inheritDoc}
*/
@Override
public String getName() {
return "AnnotationTypeOptionalMemberDetails";
}
/**
* Build the annotation type optional member documentation.
*
* @param node the XML element that specifies which components to document
* @param memberDetailsTree the content tree to which the documentation will be added
*/
public void buildAnnotationTypeOptionalMember(XMLNode node, Content memberDetailsTree) {
buildAnnotationTypeMember(node, memberDetailsTree);
}
/**
* Build the default value for this optional member.
*
* @param node the XML element that specifies which components to document
* @param annotationDocTree the content tree to which the documentation will be added
*/
public void buildDefaultValueInfo(XMLNode node, Content annotationDocTree) {
((AnnotationTypeOptionalMemberWriter) writer).addDefaultValueInfo(
(MemberDoc) members.get(currentMemberIndex),
annotationDocTree);
}
/**
* {@inheritDoc}
*/
@Override
public AnnotationTypeRequiredMemberWriter getWriter() {
return writer;
}
}

241
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/AnnotationTypeRequiredMemberBuilder.java Normal file
View File

@@ -0,0 +1,241 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* Builds documentation for required annotation type members.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public class AnnotationTypeRequiredMemberBuilder extends AbstractMemberBuilder {
/**
* The annotation type whose members are being documented.
*/
protected ClassDoc classDoc;
/**
* The visible members for the given class.
*/
protected VisibleMemberMap visibleMemberMap;
/**
* The writer to output the member documentation.
*/
protected AnnotationTypeRequiredMemberWriter writer;
/**
* The list of members being documented.
*/
protected List<ProgramElementDoc> members;
/**
* The index of the current member that is being documented at this point
* in time.
*/
protected int currentMemberIndex;
/**
* Construct a new AnnotationTypeRequiredMemberBuilder.
*
* @param context the build context.
* @param classDoc the class whose members are being documented.
* @param writer the doclet specific writer.
*/
protected AnnotationTypeRequiredMemberBuilder(Context context,
ClassDoc classDoc,
AnnotationTypeRequiredMemberWriter writer,
int memberType) {
super(context);
this.classDoc = classDoc;
this.writer = writer;
this.visibleMemberMap = new VisibleMemberMap(classDoc, memberType,
configuration);
this.members = new ArrayList<ProgramElementDoc>(
this.visibleMemberMap.getMembersFor(classDoc));
if (configuration.getMemberComparator() != null) {
Collections.sort(this.members, configuration.getMemberComparator());
}
}
/**
* Construct a new AnnotationTypeMemberBuilder.
*
* @param context the build context.
* @param classDoc the class whose members are being documented.
* @param writer the doclet specific writer.
*/
public static AnnotationTypeRequiredMemberBuilder getInstance(
Context context, ClassDoc classDoc,
AnnotationTypeRequiredMemberWriter writer) {
return new AnnotationTypeRequiredMemberBuilder(context, classDoc,
writer,
VisibleMemberMap.ANNOTATION_TYPE_MEMBER_REQUIRED);
}
/**
* {@inheritDoc}
*/
public String getName() {
return "AnnotationTypeRequiredMemberDetails";
}
/**
* Returns a list of members that will be documented for the given class.
* This information can be used for doclet specific documentation
* generation.
*
* @param classDoc the {@link ClassDoc} we want to check.
* @return a list of members that will be documented.
*/
public List<ProgramElementDoc> members(ClassDoc classDoc) {
return visibleMemberMap.getMembersFor(classDoc);
}
/**
* Returns the visible member map for the members of this class.
*
* @return the visible member map for the members of this class.
*/
public VisibleMemberMap getVisibleMemberMap() {
return visibleMemberMap;
}
/**
* summaryOrder.size()
*/
public boolean hasMembersToDocument() {
return members.size() > 0;
}
/**
* Build the annotation type required member documentation.
*
* @param node the XML element that specifies which components to document
* @param memberDetailsTree the content tree to which the documentation will be added
*/
public void buildAnnotationTypeRequiredMember(XMLNode node, Content memberDetailsTree) {
buildAnnotationTypeMember(node, memberDetailsTree);
}
/**
* Build the member documentation.
*
* @param node the XML element that specifies which components to document
* @param memberDetailsTree the content tree to which the documentation will be added
*/
public void buildAnnotationTypeMember(XMLNode node, Content memberDetailsTree) {
if (writer == null) {
return;
}
int size = members.size();
if (size > 0) {
writer.addAnnotationDetailsMarker(memberDetailsTree);
for (currentMemberIndex = 0; currentMemberIndex < size;
currentMemberIndex++) {
Content detailsTree = writer.getMemberTreeHeader();
writer.addAnnotationDetailsTreeHeader(classDoc, detailsTree);
Content annotationDocTree = writer.getAnnotationDocTreeHeader(
(MemberDoc) members.get(currentMemberIndex), detailsTree);
buildChildren(node, annotationDocTree);
detailsTree.addContent(writer.getAnnotationDoc(
annotationDocTree, (currentMemberIndex == size - 1)));
memberDetailsTree.addContent(writer.getAnnotationDetails(detailsTree));
}
}
}
/**
* Build the signature.
*
* @param node the XML element that specifies which components to document
* @param annotationDocTree the content tree to which the documentation will be added
*/
public void buildSignature(XMLNode node, Content annotationDocTree) {
annotationDocTree.addContent(
writer.getSignature((MemberDoc) members.get(currentMemberIndex)));
}
/**
* Build the deprecation information.
*
* @param node the XML element that specifies which components to document
* @param annotationDocTree the content tree to which the documentation will be added
*/
public void buildDeprecationInfo(XMLNode node, Content annotationDocTree) {
writer.addDeprecated((MemberDoc) members.get(currentMemberIndex),
annotationDocTree);
}
/**
* Build the comments for the member. Do nothing if
* {@link Configuration#nocomment} is set to true.
*
* @param node the XML element that specifies which components to document
* @param annotationDocTree the content tree to which the documentation will be added
*/
public void buildMemberComments(XMLNode node, Content annotationDocTree) {
if(! configuration.nocomment){
writer.addComments((MemberDoc) members.get(currentMemberIndex),
annotationDocTree);
}
}
/**
* Build the tag information.
*
* @param node the XML element that specifies which components to document
* @param annotationDocTree the content tree to which the documentation will be added
*/
public void buildTagInfo(XMLNode node, Content annotationDocTree) {
writer.addTags((MemberDoc) members.get(currentMemberIndex),
annotationDocTree);
}
/**
* Return the annotation type required member writer for this builder.
*
* @return the annotation type required member constant writer for this
* builder.
*/
public AnnotationTypeRequiredMemberWriter getWriter() {
return writer;
}
}

303
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/BuilderFactory.java Normal file
View File

@@ -0,0 +1,303 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.util.HashSet;
import java.util.Set;
import com.sun.javadoc.*;
import com.sun.tools.javac.jvm.Profile;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* The factory for constructing builders.
*
* <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
* @since 1.4
*/
public class BuilderFactory {
/**
* The current configuration of the doclet.
*/
private final Configuration configuration;
/**
* The factory to retrieve the required writers from.
*/
private final WriterFactory writerFactory;
private final AbstractBuilder.Context context;
/**
* Construct a builder factory using the given configuration.
* @param configuration the configuration for the current doclet
* being executed.
*/
public BuilderFactory (Configuration configuration) {
this.configuration = configuration;
this.writerFactory = configuration.getWriterFactory();
Set<String> containingPackagesSeen = new HashSet<String>();
context = new AbstractBuilder.Context(configuration, containingPackagesSeen,
LayoutParser.getInstance(configuration));
}
/**
* Return the builder that builds the constant summary.
* @return the builder that builds the constant summary.
*/
public AbstractBuilder getConstantsSummaryBuider() throws Exception {
return ConstantsSummaryBuilder.getInstance(context,
writerFactory.getConstantsSummaryWriter());
}
/**
* Return the builder that builds the package summary.
*
* @param pkg the package being documented.
* @param prevPkg the previous package being documented.
* @param nextPkg the next package being documented.
* @return the builder that builds the constant summary.
*/
public AbstractBuilder getPackageSummaryBuilder(PackageDoc pkg, PackageDoc prevPkg,
PackageDoc nextPkg) throws Exception {
return PackageSummaryBuilder.getInstance(context, pkg,
writerFactory.getPackageSummaryWriter(pkg, prevPkg, nextPkg));
}
/**
* Return the builder that builds the profile summary.
*
* @param profile the profile being documented.
* @param prevProfile the previous profile being documented.
* @param nextProfile the next profile being documented.
* @return the builder that builds the profile summary.
*/
public AbstractBuilder getProfileSummaryBuilder(Profile profile, Profile prevProfile,
Profile nextProfile) throws Exception {
return ProfileSummaryBuilder.getInstance(context, profile,
writerFactory.getProfileSummaryWriter(profile, prevProfile, nextProfile));
}
/**
* Return the builder that builds the profile package summary.
*
* @param pkg the profile package being documented.
* @param prevPkg the previous profile package being documented.
* @param nextPkg the next profile package being documented.
* @param profile the profile being documented.
* @return the builder that builds the profile package summary.
*/
public AbstractBuilder getProfilePackageSummaryBuilder(PackageDoc pkg, PackageDoc prevPkg,
PackageDoc nextPkg, Profile profile) throws Exception {
return ProfilePackageSummaryBuilder.getInstance(context, pkg,
writerFactory.getProfilePackageSummaryWriter(pkg, prevPkg, nextPkg,
profile), profile);
}
/**
* Return the builder for the class.
*
* @param classDoc the class being documented.
* @param prevClass the previous class that was documented.
* @param nextClass the next class being documented.
* @param classTree the class tree.
* @return the writer for the class. Return null if this
* writer is not supported by the doclet.
*/
public AbstractBuilder getClassBuilder(ClassDoc classDoc,
ClassDoc prevClass, ClassDoc nextClass, ClassTree classTree)
throws Exception {
return ClassBuilder.getInstance(context, classDoc,
writerFactory.getClassWriter(classDoc, prevClass, nextClass,
classTree));
}
/**
* Return the builder for the annotation type.
*
* @param annotationType the annotation type being documented.
* @param prevType the previous type that was documented.
* @param nextType the next type being documented.
* @return the writer for the annotation type. Return null if this
* writer is not supported by the doclet.
*/
public AbstractBuilder getAnnotationTypeBuilder(
AnnotationTypeDoc annotationType,
Type prevType, Type nextType)
throws Exception {
return AnnotationTypeBuilder.getInstance(context, annotationType,
writerFactory.getAnnotationTypeWriter(annotationType, prevType, nextType));
}
/**
* Return an instance of the method builder for the given class.
*
* @return an instance of the method builder for the given class.
*/
public AbstractBuilder getMethodBuilder(ClassWriter classWriter)
throws Exception {
return MethodBuilder.getInstance(context,
classWriter.getClassDoc(),
writerFactory.getMethodWriter(classWriter));
}
/**
* Return an instance of the annotation type fields builder for the given
* class.
*
* @return an instance of the annotation type field builder for the given
* annotation type.
*/
public AbstractBuilder getAnnotationTypeFieldsBuilder(
AnnotationTypeWriter annotationTypeWriter)
throws Exception {
return AnnotationTypeFieldBuilder.getInstance(context,
annotationTypeWriter.getAnnotationTypeDoc(),
writerFactory.getAnnotationTypeFieldWriter(
annotationTypeWriter));
}
/**
* Return an instance of the annotation type member builder for the given
* class.
*
* @return an instance of the annotation type member builder for the given
* annotation type.
*/
public AbstractBuilder getAnnotationTypeOptionalMemberBuilder(
AnnotationTypeWriter annotationTypeWriter)
throws Exception {
return AnnotationTypeOptionalMemberBuilder.getInstance(context,
annotationTypeWriter.getAnnotationTypeDoc(),
writerFactory.getAnnotationTypeOptionalMemberWriter(
annotationTypeWriter));
}
/**
* Return an instance of the annotation type member builder for the given
* class.
*
* @return an instance of the annotation type member builder for the given
* annotation type.
*/
public AbstractBuilder getAnnotationTypeRequiredMemberBuilder(
AnnotationTypeWriter annotationTypeWriter)
throws Exception {
return AnnotationTypeRequiredMemberBuilder.getInstance(context,
annotationTypeWriter.getAnnotationTypeDoc(),
writerFactory.getAnnotationTypeRequiredMemberWriter(
annotationTypeWriter));
}
/**
* Return an instance of the enum constants builder for the given class.
*
* @return an instance of the enum constants builder for the given class.
*/
public AbstractBuilder getEnumConstantsBuilder(ClassWriter classWriter)
throws Exception {
return EnumConstantBuilder.getInstance(context, classWriter.getClassDoc(),
writerFactory.getEnumConstantWriter(classWriter));
}
/**
* Return an instance of the field builder for the given class.
*
* @return an instance of the field builder for the given class.
*/
public AbstractBuilder getFieldBuilder(ClassWriter classWriter)
throws Exception {
return FieldBuilder.getInstance(context, classWriter.getClassDoc(),
writerFactory.getFieldWriter(classWriter));
}
/**
* Return an instance of the property builder for the given class.
*
* @return an instance of the field builder for the given class.
*/
public AbstractBuilder getPropertyBuilder(ClassWriter classWriter) throws Exception {
final PropertyWriter propertyWriter =
writerFactory.getPropertyWriter(classWriter);
return PropertyBuilder.getInstance(context,
classWriter.getClassDoc(),
propertyWriter);
}
/**
* Return an instance of the constructor builder for the given class.
*
* @return an instance of the constructor builder for the given class.
*/
public AbstractBuilder getConstructorBuilder(ClassWriter classWriter)
throws Exception {
return ConstructorBuilder.getInstance(context,
classWriter.getClassDoc(),
writerFactory.getConstructorWriter(classWriter));
}
/**
* Return an instance of the member summary builder for the given class.
*
* @return an instance of the member summary builder for the given class.
*/
public AbstractBuilder getMemberSummaryBuilder(ClassWriter classWriter)
throws Exception {
return MemberSummaryBuilder.getInstance(classWriter, context);
}
/**
* Return an instance of the member summary builder for the given annotation
* type.
*
* @return an instance of the member summary builder for the given
* annotation type.
*/
public AbstractBuilder getMemberSummaryBuilder(
AnnotationTypeWriter annotationTypeWriter)
throws Exception {
return MemberSummaryBuilder.getInstance(annotationTypeWriter, context);
}
/**
* Return the builder that builds the serialized form.
*
* @return the builder that builds the serialized form.
*/
public AbstractBuilder getSerializedFormBuilder()
throws Exception {
return SerializedFormBuilder.getInstance(context);
}
}

418
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/ClassBuilder.java Normal file
View File

@@ -0,0 +1,418 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.io.*;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* Builds the summary for a given class.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public class ClassBuilder extends AbstractBuilder {
/**
* The root element of the class XML is {@value}.
*/
public static final String ROOT = "ClassDoc";
/**
* The class being documented.
*/
private final ClassDoc classDoc;
/**
* The doclet specific writer.
*/
private final ClassWriter writer;
/**
* Keep track of whether or not this classdoc is an interface.
*/
private final boolean isInterface;
/**
* Keep track of whether or not this classdoc is an enum.
*/
private final boolean isEnum;
/**
* The content tree for the class documentation.
*/
private Content contentTree;
/**
* Construct a new ClassBuilder.
*
* @param context the build context
* @param classDoc the class being documented.
* @param writer the doclet specific writer.
*/
private ClassBuilder(Context context,
ClassDoc classDoc, ClassWriter writer) {
super(context);
this.classDoc = classDoc;
this.writer = writer;
if (classDoc.isInterface()) {
isInterface = true;
isEnum = false;
} else if (classDoc.isEnum()) {
isInterface = false;
isEnum = true;
Util.setEnumDocumentation(configuration, classDoc);
} else {
isInterface = false;
isEnum = false;
}
}
/**
* Construct a new ClassBuilder.
*
* @param context the build context
* @param classDoc the class being documented.
* @param writer the doclet specific writer.
*/
public static ClassBuilder getInstance(Context context,
ClassDoc classDoc, ClassWriter writer) {
return new ClassBuilder(context, classDoc, writer);
}
/**
* {@inheritDoc}
*/
public void build() throws IOException {
build(layoutParser.parseXML(ROOT), contentTree);
}
/**
* {@inheritDoc}
*/
public String getName() {
return ROOT;
}
/**
* Handles the {@literal <ClassDoc>} tag.
*
* @param node the XML element that specifies which components to document
* @param contentTree the content tree to which the documentation will be added
*/
public void buildClassDoc(XMLNode node, Content contentTree) throws Exception {
String key;
if (isInterface) {
key = "doclet.Interface";
} else if (isEnum) {
key = "doclet.Enum";
} else {
key = "doclet.Class";
}
contentTree = writer.getHeader(configuration.getText(key) + " " +
classDoc.name());
Content classContentTree = writer.getClassContentHeader();
buildChildren(node, classContentTree);
contentTree.addContent(classContentTree);
writer.addFooter(contentTree);
writer.printDocument(contentTree);
writer.close();
copyDocFiles();
}
/**
* Build the class tree documentation.
*
* @param node the XML element that specifies which components to document
* @param classContentTree the content tree to which the documentation will be added
*/
public void buildClassTree(XMLNode node, Content classContentTree) {
writer.addClassTree(classContentTree);
}
/**
* Build the class information tree documentation.
*
* @param node the XML element that specifies which components to document
* @param classContentTree the content tree to which the documentation will be added
*/
public void buildClassInfo(XMLNode node, Content classContentTree) {
Content classInfoTree = writer.getClassInfoTreeHeader();
buildChildren(node, classInfoTree);
classContentTree.addContent(writer.getClassInfo(classInfoTree));
}
/**
* Build the typeparameters of this class.
*
* @param node the XML element that specifies which components to document
* @param classInfoTree the content tree to which the documentation will be added
*/
public void buildTypeParamInfo(XMLNode node, Content classInfoTree) {
writer.addTypeParamInfo(classInfoTree);
}
/**
* If this is an interface, list all super interfaces.
*
* @param node the XML element that specifies which components to document
* @param classInfoTree the content tree to which the documentation will be added
*/
public void buildSuperInterfacesInfo(XMLNode node, Content classInfoTree) {
writer.addSuperInterfacesInfo(classInfoTree);
}
/**
* If this is a class, list all interfaces implemented by this class.
*
* @param node the XML element that specifies which components to document
* @param classInfoTree the content tree to which the documentation will be added
*/
public void buildImplementedInterfacesInfo(XMLNode node, Content classInfoTree) {
writer.addImplementedInterfacesInfo(classInfoTree);
}
/**
* List all the classes extend this one.
*
* @param node the XML element that specifies which components to document
* @param classInfoTree the content tree to which the documentation will be added
*/
public void buildSubClassInfo(XMLNode node, Content classInfoTree) {
writer.addSubClassInfo(classInfoTree);
}
/**
* List all the interfaces that extend this one.
*
* @param node the XML element that specifies which components to document
* @param classInfoTree the content tree to which the documentation will be added
*/
public void buildSubInterfacesInfo(XMLNode node, Content classInfoTree) {
writer.addSubInterfacesInfo(classInfoTree);
}
/**
* If this is an interface, list all classes that implement this interface.
*
* @param node the XML element that specifies which components to document
* @param classInfoTree the content tree to which the documentation will be added
*/
public void buildInterfaceUsageInfo(XMLNode node, Content classInfoTree) {
writer.addInterfaceUsageInfo(classInfoTree);
}
/**
* If this is an functional interface, display appropriate message.
*
* @param node the XML element that specifies which components to document
* @param classInfoTree the content tree to which the documentation will be added
*/
public void buildFunctionalInterfaceInfo(XMLNode node, Content classInfoTree) {
writer.addFunctionalInterfaceInfo(classInfoTree);
}
/**
* If this class is deprecated, build the appropriate information.
*
* @param node the XML element that specifies which components to document
* @param classInfoTree the content tree to which the documentation will be added
*/
public void buildDeprecationInfo (XMLNode node, Content classInfoTree) {
writer.addClassDeprecationInfo(classInfoTree);
}
/**
* If this is an inner class or interface, list the enclosing class or interface.
*
* @param node the XML element that specifies which components to document
* @param classInfoTree the content tree to which the documentation will be added
*/
public void buildNestedClassInfo (XMLNode node, Content classInfoTree) {
writer.addNestedClassInfo(classInfoTree);
}
/**
* Copy the doc files for the current ClassDoc if necessary.
*/
private void copyDocFiles() {
PackageDoc containingPackage = classDoc.containingPackage();
if((configuration.packages == null ||
Arrays.binarySearch(configuration.packages,
containingPackage) < 0) &&
! containingPackagesSeen.contains(containingPackage.name())){
//Only copy doc files dir if the containing package is not
//documented AND if we have not documented a class from the same
//package already. Otherwise, we are making duplicate copies.
Util.copyDocFiles(configuration, containingPackage);
containingPackagesSeen.add(containingPackage.name());
}
}
/**
* Build the signature of the current class.
*
* @param node the XML element that specifies which components to document
* @param classInfoTree the content tree to which the documentation will be added
*/
public void buildClassSignature(XMLNode node, Content classInfoTree) {
StringBuilder modifiers = new StringBuilder(classDoc.modifiers());
modifiers.append(modifiers.length() == 0 ? "" : " ");
if (isEnum) {
modifiers.append("enum ");
int index;
if ((index = modifiers.indexOf("abstract")) >= 0) {
modifiers.delete(index, index + "abstract".length());
modifiers = new StringBuilder(
Util.replaceText(modifiers.toString(), " ", " "));
}
if ((index = modifiers.indexOf("final")) >= 0) {
modifiers.delete(index, index + "final".length());
modifiers = new StringBuilder(
Util.replaceText(modifiers.toString(), " ", " "));
}
//} else if (classDoc.isAnnotationType()) {
//modifiers.append("@interface ");
} else if (! isInterface) {
modifiers.append("class ");
}
writer.addClassSignature(modifiers.toString(), classInfoTree);
}
/**
* Build the class description.
*
* @param node the XML element that specifies which components to document
* @param classInfoTree the content tree to which the documentation will be added
*/
public void buildClassDescription(XMLNode node, Content classInfoTree) {
writer.addClassDescription(classInfoTree);
}
/**
* Build the tag information for the current class.
*
* @param node the XML element that specifies which components to document
* @param classInfoTree the content tree to which the documentation will be added
*/
public void buildClassTagInfo(XMLNode node, Content classInfoTree) {
writer.addClassTagInfo(classInfoTree);
}
/**
* Build the member summary contents of the page.
*
* @param node the XML element that specifies which components to document
* @param classContentTree the content tree to which the documentation will be added
*/
public void buildMemberSummary(XMLNode node, Content classContentTree) throws Exception {
Content memberSummaryTree = writer.getMemberTreeHeader();
configuration.getBuilderFactory().
getMemberSummaryBuilder(writer).buildChildren(node, memberSummaryTree);
classContentTree.addContent(writer.getMemberSummaryTree(memberSummaryTree));
}
/**
* Build the member details contents of the page.
*
* @param node the XML element that specifies which components to document
* @param classContentTree the content tree to which the documentation will be added
*/
public void buildMemberDetails(XMLNode node, Content classContentTree) {
Content memberDetailsTree = writer.getMemberTreeHeader();
buildChildren(node, memberDetailsTree);
classContentTree.addContent(writer.getMemberDetailsTree(memberDetailsTree));
}
/**
* Build the enum constants documentation.
*
* @param node the XML element that specifies which components to document
* @param memberDetailsTree the content tree to which the documentation will be added
*/
public void buildEnumConstantsDetails(XMLNode node,
Content memberDetailsTree) throws Exception {
configuration.getBuilderFactory().
getEnumConstantsBuilder(writer).buildChildren(node, memberDetailsTree);
}
/**
* Build the field documentation.
*
* @param node the XML element that specifies which components to document
* @param memberDetailsTree the content tree to which the documentation will be added
*/
public void buildFieldDetails(XMLNode node,
Content memberDetailsTree) throws Exception {
configuration.getBuilderFactory().
getFieldBuilder(writer).buildChildren(node, memberDetailsTree);
}
/**
* Build the property documentation.
*
* @param elements the XML elements that specify how a field is documented.
*/
public void buildPropertyDetails(XMLNode node,
Content memberDetailsTree) throws Exception {
configuration.getBuilderFactory().
getPropertyBuilder(writer).buildChildren(node, memberDetailsTree);
}
/**
* Build the constructor documentation.
*
* @param node the XML element that specifies which components to document
* @param memberDetailsTree the content tree to which the documentation will be added
*/
public void buildConstructorDetails(XMLNode node,
Content memberDetailsTree) throws Exception {
configuration.getBuilderFactory().
getConstructorBuilder(writer).buildChildren(node, memberDetailsTree);
}
/**
* Build the method documentation.
*
* @param node the XML element that specifies which components to document
* @param memberDetailsTree the content tree to which the documentation will be added
*/
public void buildMethodDetails(XMLNode node,
Content memberDetailsTree) throws Exception {
configuration.getBuilderFactory().
getMethodBuilder(writer).buildChildren(node, memberDetailsTree);
}
}

386
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/ConstantsSummaryBuilder.java Normal file
View File

@@ -0,0 +1,386 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.io.*;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* Builds the Constants Summary Page.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public class ConstantsSummaryBuilder extends AbstractBuilder {
/**
* The root element of the constant summary XML is {@value}.
*/
public static final String ROOT = "ConstantSummary";
/**
* The maximum number of package directories shown in the constant
* value index.
*/
public static final int MAX_CONSTANT_VALUE_INDEX_LENGTH = 2;
/**
* The writer used to write the results.
*/
protected final ConstantsSummaryWriter writer;
/**
* The set of ClassDocs that have constant fields.
*/
protected final Set<ClassDoc> classDocsWithConstFields;
/**
* The set of printed package headers.
*/
protected Set<String> printedPackageHeaders;
/**
* The current package being documented.
*/
private PackageDoc currentPackage;
/**
* The current class being documented.
*/
private ClassDoc currentClass;
/**
* The content tree for the constant summary documentation.
*/
private Content contentTree;
/**
* Construct a new ConstantsSummaryBuilder.
*
* @param context the build context.
* @param writer the writer for the summary.
*/
private ConstantsSummaryBuilder(Context context,
ConstantsSummaryWriter writer) {
super(context);
this.writer = writer;
this.classDocsWithConstFields = new HashSet<ClassDoc>();
}
/**
* Construct a ConstantsSummaryBuilder.
*
* @param context the build context.
* @param writer the writer for the summary.
*/
public static ConstantsSummaryBuilder getInstance(Context context,
ConstantsSummaryWriter writer) {
return new ConstantsSummaryBuilder(context, writer);
}
/**
* {@inheritDoc}
*/
public void build() throws IOException {
if (writer == null) {
//Doclet does not support this output.
return;
}
build(layoutParser.parseXML(ROOT), contentTree);
}
/**
* {@inheritDoc}
*/
public String getName() {
return ROOT;
}
/**
* Build the constant summary.
*
* @param node the XML element that specifies which components to document
* @param contentTree the content tree to which the documentation will be added
*/
public void buildConstantSummary(XMLNode node, Content contentTree) throws Exception {
contentTree = writer.getHeader();
buildChildren(node, contentTree);
writer.addFooter(contentTree);
writer.printDocument(contentTree);
writer.close();
}
/**
* Build the list of packages.
*
* @param node the XML element that specifies which components to document
* @param contentTree the content tree to which the content list will be added
*/
public void buildContents(XMLNode node, Content contentTree) {
Content contentListTree = writer.getContentsHeader();
PackageDoc[] packages = configuration.packages;
printedPackageHeaders = new HashSet<String>();
for (int i = 0; i < packages.length; i++) {
if (hasConstantField(packages[i]) && ! hasPrintedPackageIndex(packages[i].name())) {
writer.addLinkToPackageContent(packages[i],
parsePackageName(packages[i].name()),
printedPackageHeaders, contentListTree);
}
}
contentTree.addContent(writer.getContentsList(contentListTree));
}
/**
* Build the summary for each documented package.
*
* @param node the XML element that specifies which components to document
* @param contentTree the tree to which the summaries will be added
*/
public void buildConstantSummaries(XMLNode node, Content contentTree) {
PackageDoc[] packages = configuration.packages;
printedPackageHeaders = new HashSet<String>();
Content summariesTree = writer.getConstantSummaries();
for (int i = 0; i < packages.length; i++) {
if (hasConstantField(packages[i])) {
currentPackage = packages[i];
//Build the documentation for the current package.
buildChildren(node, summariesTree);
}
}
contentTree.addContent(summariesTree);
}
/**
* Build the header for the given package.
*
* @param node the XML element that specifies which components to document
* @param summariesTree the tree to which the package header will be added
*/
public void buildPackageHeader(XMLNode node, Content summariesTree) {
String parsedPackageName = parsePackageName(currentPackage.name());
if (! printedPackageHeaders.contains(parsedPackageName)) {
writer.addPackageName(currentPackage,
parsePackageName(currentPackage.name()), summariesTree);
printedPackageHeaders.add(parsedPackageName);
}
}
/**
* Build the summary for the current class.
*
* @param node the XML element that specifies which components to document
* @param summariesTree the tree to which the class constant summary will be added
*/
public void buildClassConstantSummary(XMLNode node, Content summariesTree) {
ClassDoc[] classes = currentPackage.name().length() > 0 ?
currentPackage.allClasses() :
configuration.classDocCatalog.allClasses(
DocletConstants.DEFAULT_PACKAGE_NAME);
Arrays.sort(classes);
Content classConstantTree = writer.getClassConstantHeader();
for (int i = 0; i < classes.length; i++) {
if (! classDocsWithConstFields.contains(classes[i]) ||
! classes[i].isIncluded()) {
continue;
}
currentClass = classes[i];
//Build the documentation for the current class.
buildChildren(node, classConstantTree);
}
summariesTree.addContent(classConstantTree);
}
/**
* Build the summary of constant members in the class.
*
* @param node the XML element that specifies which components to document
* @param classConstantTree the tree to which the constant members table
* will be added
*/
public void buildConstantMembers(XMLNode node, Content classConstantTree) {
new ConstantFieldBuilder(currentClass).buildMembersSummary(node, classConstantTree);
}
/**
* Return true if the given package has constant fields to document.
*
* @param pkg the package being checked.
* @return true if the given package has constant fields to document.
*/
private boolean hasConstantField(PackageDoc pkg) {
ClassDoc[] classes;
if (pkg.name().length() > 0) {
classes = pkg.allClasses();
} else {
classes = configuration.classDocCatalog.allClasses(
DocletConstants.DEFAULT_PACKAGE_NAME);
}
boolean found = false;
for (int j = 0; j < classes.length; j++){
if (classes[j].isIncluded() && hasConstantField(classes[j])) {
found = true;
}
}
return found;
}
/**
* Return true if the given class has constant fields to document.
*
* @param classDoc the class being checked.
* @return true if the given package has constant fields to document.
*/
private boolean hasConstantField (ClassDoc classDoc) {
VisibleMemberMap visibleMemberMapFields = new VisibleMemberMap(classDoc,
VisibleMemberMap.FIELDS, configuration);
List<?> fields = visibleMemberMapFields.getLeafClassMembers(configuration);
for (Iterator<?> iter = fields.iterator(); iter.hasNext(); ) {
FieldDoc field = (FieldDoc) iter.next();
if (field.constantValueExpression() != null) {
classDocsWithConstFields.add(classDoc);
return true;
}
}
return false;
}
/**
* Return true if the given package name has been printed. Also
* return true if the root of this package has been printed.
*
* @param pkgname the name of the package to check.
*/
private boolean hasPrintedPackageIndex(String pkgname) {
String[] list = printedPackageHeaders.toArray(new String[] {});
for (int i = 0; i < list.length; i++) {
if (pkgname.startsWith(list[i])) {
return true;
}
}
return false;
}
/**
* Print the table of constants.
*
* @author Jamie Ho
* @since 1.4
*/
private class ConstantFieldBuilder {
/**
* The map used to get the visible variables.
*/
protected VisibleMemberMap visibleMemberMapFields = null;
/**
* The map used to get the visible variables.
*/
protected VisibleMemberMap visibleMemberMapEnumConst = null;
/**
* The classdoc that we are examining constants for.
*/
protected ClassDoc classdoc;
/**
* Construct a ConstantFieldSubWriter.
* @param classdoc the classdoc that we are examining constants for.
*/
public ConstantFieldBuilder(ClassDoc classdoc) {
this.classdoc = classdoc;
visibleMemberMapFields = new VisibleMemberMap(classdoc,
VisibleMemberMap.FIELDS, configuration);
visibleMemberMapEnumConst = new VisibleMemberMap(classdoc,
VisibleMemberMap.ENUM_CONSTANTS, configuration);
}
/**
* Builds the table of constants for a given class.
*
* @param node the XML element that specifies which components to document
* @param classConstantTree the tree to which the class constants table
* will be added
*/
protected void buildMembersSummary(XMLNode node, Content classConstantTree) {
List<FieldDoc> members = new ArrayList<FieldDoc>(members());
if (members.size() > 0) {
Collections.sort(members);
writer.addConstantMembers(classdoc, members, classConstantTree);
}
}
/**
* Return the list of visible constant fields for the given classdoc.
* @return the list of visible constant fields for the given classdoc.
*/
protected List<FieldDoc> members() {
List<ProgramElementDoc> l = visibleMemberMapFields.getLeafClassMembers(configuration);
l.addAll(visibleMemberMapEnumConst.getLeafClassMembers(configuration));
Iterator<ProgramElementDoc> iter;
if(l != null){
iter = l.iterator();
} else {
return null;
}
List<FieldDoc> inclList = new LinkedList<FieldDoc>();
FieldDoc member;
while(iter.hasNext()){
member = (FieldDoc)iter.next();
if(member.constantValue() != null){
inclList.add(member);
}
}
return inclList;
}
}
/**
* Parse the package name. We only want to display package name up to
* 2 levels.
*/
private String parsePackageName(String pkgname) {
int index = -1;
for (int j = 0; j < MAX_CONSTANT_VALUE_INDEX_LENGTH; j++) {
index = pkgname.indexOf(".", index + 1);
}
if (index != -1) {
pkgname = pkgname.substring(0, index);
}
return pkgname;
}
}

232
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/ConstructorBuilder.java Normal file
View File

@@ -0,0 +1,232 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* Builds documentation for a constructor.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public class ConstructorBuilder extends AbstractMemberBuilder {
/**
* The name of this builder.
*/
public static final String NAME = "ConstructorDetails";
/**
* The index of the current field that is being documented at this point
* in time.
*/
private int currentConstructorIndex;
/**
* The class whose constructors are being documented.
*/
private final ClassDoc classDoc;
/**
* The visible constructors for the given class.
*/
private final VisibleMemberMap visibleMemberMap;
/**
* The writer to output the constructor documentation.
*/
private final ConstructorWriter writer;
/**
* The constructors being documented.
*/
private final List<ProgramElementDoc> constructors;
/**
* Construct a new ConstructorBuilder.
*
* @param context the build context.
* @param classDoc the class whoses members are being documented.
* @param writer the doclet specific writer.
*/
private ConstructorBuilder(Context context,
ClassDoc classDoc,
ConstructorWriter writer) {
super(context);
this.classDoc = classDoc;
this.writer = writer;
visibleMemberMap =
new VisibleMemberMap(
classDoc,
VisibleMemberMap.CONSTRUCTORS,
configuration);
constructors =
new ArrayList<ProgramElementDoc>(visibleMemberMap.getMembersFor(classDoc));
for (int i = 0; i < constructors.size(); i++) {
if (constructors.get(i).isProtected()
|| constructors.get(i).isPrivate()) {
writer.setFoundNonPubConstructor(true);
}
}
if (configuration.getMemberComparator() != null) {
Collections.sort(constructors,configuration.getMemberComparator());
}
}
/**
* Construct a new ConstructorBuilder.
*
* @param context the build context.
* @param classDoc the class whoses members are being documented.
* @param writer the doclet specific writer.
*/
public static ConstructorBuilder getInstance(Context context,
ClassDoc classDoc, ConstructorWriter writer) {
return new ConstructorBuilder(context, classDoc, writer);
}
/**
* {@inheritDoc}
*/
public String getName() {
return NAME;
}
/**
* {@inheritDoc}
*/
public boolean hasMembersToDocument() {
return constructors.size() > 0;
}
/**
* Returns a list of constructors that will be documented for the given class.
* This information can be used for doclet specific documentation
* generation.
*
* @return a list of constructors that will be documented.
*/
public List<ProgramElementDoc> members(ClassDoc classDoc) {
return visibleMemberMap.getMembersFor(classDoc);
}
/**
* Return the constructor writer for this builder.
*
* @return the constructor writer for this builder.
*/
public ConstructorWriter getWriter() {
return writer;
}
/**
* Build the constructor documentation.
*
* @param node the XML element that specifies which components to document
* @param memberDetailsTree the content tree to which the documentation will be added
*/
public void buildConstructorDoc(XMLNode node, Content memberDetailsTree) {
if (writer == null) {
return;
}
int size = constructors.size();
if (size > 0) {
Content constructorDetailsTree = writer.getConstructorDetailsTreeHeader(
classDoc, memberDetailsTree);
for (currentConstructorIndex = 0; currentConstructorIndex < size;
currentConstructorIndex++) {
Content constructorDocTree = writer.getConstructorDocTreeHeader(
(ConstructorDoc) constructors.get(currentConstructorIndex),
constructorDetailsTree);
buildChildren(node, constructorDocTree);
constructorDetailsTree.addContent(writer.getConstructorDoc(
constructorDocTree, (currentConstructorIndex == size - 1)));
}
memberDetailsTree.addContent(
writer.getConstructorDetails(constructorDetailsTree));
}
}
/**
* Build the signature.
*
* @param node the XML element that specifies which components to document
* @param constructorDocTree the content tree to which the documentation will be added
*/
public void buildSignature(XMLNode node, Content constructorDocTree) {
constructorDocTree.addContent(
writer.getSignature(
(ConstructorDoc) constructors.get(currentConstructorIndex)));
}
/**
* Build the deprecation information.
*
* @param node the XML element that specifies which components to document
* @param constructorDocTree the content tree to which the documentation will be added
*/
public void buildDeprecationInfo(XMLNode node, Content constructorDocTree) {
writer.addDeprecated(
(ConstructorDoc) constructors.get(currentConstructorIndex), constructorDocTree);
}
/**
* Build the comments for the constructor. Do nothing if
* {@link Configuration#nocomment} is set to true.
*
* @param node the XML element that specifies which components to document
* @param constructorDocTree the content tree to which the documentation will be added
*/
public void buildConstructorComments(XMLNode node, Content constructorDocTree) {
if (!configuration.nocomment) {
writer.addComments(
(ConstructorDoc) constructors.get(currentConstructorIndex),
constructorDocTree);
}
}
/**
* Build the tag information.
*
* @param node the XML element that specifies which components to document
* @param constructorDocTree the content tree to which the documentation will be added
*/
public void buildTagInfo(XMLNode node, Content constructorDocTree) {
writer.addTags((ConstructorDoc) constructors.get(currentConstructorIndex),
constructorDocTree);
}
}

231
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/EnumConstantBuilder.java Normal file
View File

@@ -0,0 +1,231 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* Builds documentation for a enum constants.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public class EnumConstantBuilder extends AbstractMemberBuilder {
/**
* The class whose enum constants are being documented.
*/
private final ClassDoc classDoc;
/**
* The visible enum constantss for the given class.
*/
private final VisibleMemberMap visibleMemberMap;
/**
* The writer to output the enum constants documentation.
*/
private final EnumConstantWriter writer;
/**
* The list of enum constants being documented.
*/
private final List<ProgramElementDoc> enumConstants;
/**
* The index of the current enum constant that is being documented at this point
* in time.
*/
private int currentEnumConstantsIndex;
/**
* Construct a new EnumConstantsBuilder.
*
* @param context the build context.
* @param classDoc the class whoses members are being documented.
* @param writer the doclet specific writer.
*/
private EnumConstantBuilder(Context context,
ClassDoc classDoc, EnumConstantWriter writer) {
super(context);
this.classDoc = classDoc;
this.writer = writer;
visibleMemberMap =
new VisibleMemberMap(
classDoc,
VisibleMemberMap.ENUM_CONSTANTS,
configuration);
enumConstants =
new ArrayList<ProgramElementDoc>(visibleMemberMap.getMembersFor(classDoc));
if (configuration.getMemberComparator() != null) {
Collections.sort(enumConstants, configuration.getMemberComparator());
}
}
/**
* Construct a new EnumConstantsBuilder.
*
* @param context the build context.
* @param classDoc the class whoses members are being documented.
* @param writer the doclet specific writer.
*/
public static EnumConstantBuilder getInstance(Context context,
ClassDoc classDoc, EnumConstantWriter writer) {
return new EnumConstantBuilder(context, classDoc, writer);
}
/**
* {@inheritDoc}
*/
public String getName() {
return "EnumConstantDetails";
}
/**
* Returns a list of enum constants that will be documented for the given class.
* This information can be used for doclet specific documentation
* generation.
*
* @param classDoc the {@link ClassDoc} we want to check.
* @return a list of enum constants that will be documented.
*/
public List<ProgramElementDoc> members(ClassDoc classDoc) {
return visibleMemberMap.getMembersFor(classDoc);
}
/**
* Returns the visible member map for the enum constants of this class.
*
* @return the visible member map for the enum constants of this class.
*/
public VisibleMemberMap getVisibleMemberMap() {
return visibleMemberMap;
}
/**
* summaryOrder.size()
*/
public boolean hasMembersToDocument() {
return enumConstants.size() > 0;
}
/**
* Build the enum constant documentation.
*
* @param node the XML element that specifies which components to document
* @param memberDetailsTree the content tree to which the documentation will be added
*/
public void buildEnumConstant(XMLNode node, Content memberDetailsTree) {
if (writer == null) {
return;
}
int size = enumConstants.size();
if (size > 0) {
Content enumConstantsDetailsTree = writer.getEnumConstantsDetailsTreeHeader(
classDoc, memberDetailsTree);
for (currentEnumConstantsIndex = 0; currentEnumConstantsIndex < size;
currentEnumConstantsIndex++) {
Content enumConstantsTree = writer.getEnumConstantsTreeHeader(
(FieldDoc) enumConstants.get(currentEnumConstantsIndex),
enumConstantsDetailsTree);
buildChildren(node, enumConstantsTree);
enumConstantsDetailsTree.addContent(writer.getEnumConstants(
enumConstantsTree, (currentEnumConstantsIndex == size - 1)));
}
memberDetailsTree.addContent(
writer.getEnumConstantsDetails(enumConstantsDetailsTree));
}
}
/**
* Build the signature.
*
* @param node the XML element that specifies which components to document
* @param enumConstantsTree the content tree to which the documentation will be added
*/
public void buildSignature(XMLNode node, Content enumConstantsTree) {
enumConstantsTree.addContent(writer.getSignature(
(FieldDoc) enumConstants.get(currentEnumConstantsIndex)));
}
/**
* Build the deprecation information.
*
* @param node the XML element that specifies which components to document
* @param enumConstantsTree the content tree to which the documentation will be added
*/
public void buildDeprecationInfo(XMLNode node, Content enumConstantsTree) {
writer.addDeprecated(
(FieldDoc) enumConstants.get(currentEnumConstantsIndex),
enumConstantsTree);
}
/**
* Build the comments for the enum constant. Do nothing if
* {@link Configuration#nocomment} is set to true.
*
* @param node the XML element that specifies which components to document
* @param enumConstantsTree the content tree to which the documentation will be added
*/
public void buildEnumConstantComments(XMLNode node, Content enumConstantsTree) {
if (!configuration.nocomment) {
writer.addComments(
(FieldDoc) enumConstants.get(currentEnumConstantsIndex),
enumConstantsTree);
}
}
/**
* Build the tag information.
*
* @param node the XML element that specifies which components to document
* @param enumConstantsTree the content tree to which the documentation will be added
*/
public void buildTagInfo(XMLNode node, Content enumConstantsTree) {
writer.addTags(
(FieldDoc) enumConstants.get(currentEnumConstantsIndex),
enumConstantsTree);
}
/**
* Return the enum constant writer for this builder.
*
* @return the enum constant writer for this builder.
*/
public EnumConstantWriter getWriter() {
return writer;
}
}

229
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/FieldBuilder.java Normal file
View File

@@ -0,0 +1,229 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* Builds documentation for a field.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public class FieldBuilder extends AbstractMemberBuilder {
/**
* The class whose fields are being documented.
*/
private final ClassDoc classDoc;
/**
* The visible fields for the given class.
*/
private final VisibleMemberMap visibleMemberMap;
/**
* The writer to output the field documentation.
*/
private final FieldWriter writer;
/**
* The list of fields being documented.
*/
private final List<ProgramElementDoc> fields;
/**
* The index of the current field that is being documented at this point
* in time.
*/
private int currentFieldIndex;
/**
* Construct a new FieldBuilder.
*
* @param context the build context.
* @param classDoc the class whoses members are being documented.
* @param writer the doclet specific writer.
*/
private FieldBuilder(Context context,
ClassDoc classDoc,
FieldWriter writer) {
super(context);
this.classDoc = classDoc;
this.writer = writer;
visibleMemberMap =
new VisibleMemberMap(
classDoc,
VisibleMemberMap.FIELDS,
configuration);
fields =
new ArrayList<ProgramElementDoc>(visibleMemberMap.getLeafClassMembers(
configuration));
if (configuration.getMemberComparator() != null) {
Collections.sort(fields, configuration.getMemberComparator());
}
}
/**
* Construct a new FieldBuilder.
*
* @param context the build context.
* @param classDoc the class whoses members are being documented.
* @param writer the doclet specific writer.
*/
public static FieldBuilder getInstance(Context context,
ClassDoc classDoc,
FieldWriter writer) {
return new FieldBuilder(context, classDoc, writer);
}
/**
* {@inheritDoc}
*/
public String getName() {
return "FieldDetails";
}
/**
* Returns a list of fields that will be documented for the given class.
* This information can be used for doclet specific documentation
* generation.
*
* @param classDoc the {@link ClassDoc} we want to check.
* @return a list of fields that will be documented.
*/
public List<ProgramElementDoc> members(ClassDoc classDoc) {
return visibleMemberMap.getMembersFor(classDoc);
}
/**
* Returns the visible member map for the fields of this class.
*
* @return the visible member map for the fields of this class.
*/
public VisibleMemberMap getVisibleMemberMap() {
return visibleMemberMap;
}
/**
* summaryOrder.size()
*/
public boolean hasMembersToDocument() {
return fields.size() > 0;
}
/**
* Build the field documentation.
*
* @param node the XML element that specifies which components to document
* @param memberDetailsTree the content tree to which the documentation will be added
*/
public void buildFieldDoc(XMLNode node, Content memberDetailsTree) {
if (writer == null) {
return;
}
int size = fields.size();
if (size > 0) {
Content fieldDetailsTree = writer.getFieldDetailsTreeHeader(
classDoc, memberDetailsTree);
for (currentFieldIndex = 0; currentFieldIndex < size;
currentFieldIndex++) {
Content fieldDocTree = writer.getFieldDocTreeHeader(
(FieldDoc) fields.get(currentFieldIndex),
fieldDetailsTree);
buildChildren(node, fieldDocTree);
fieldDetailsTree.addContent(writer.getFieldDoc(
fieldDocTree, (currentFieldIndex == size - 1)));
}
memberDetailsTree.addContent(
writer.getFieldDetails(fieldDetailsTree));
}
}
/**
* Build the signature.
*
* @param node the XML element that specifies which components to document
* @param fieldDocTree the content tree to which the documentation will be added
*/
public void buildSignature(XMLNode node, Content fieldDocTree) {
fieldDocTree.addContent(
writer.getSignature((FieldDoc) fields.get(currentFieldIndex)));
}
/**
* Build the deprecation information.
*
* @param node the XML element that specifies which components to document
* @param fieldDocTree the content tree to which the documentation will be added
*/
public void buildDeprecationInfo(XMLNode node, Content fieldDocTree) {
writer.addDeprecated(
(FieldDoc) fields.get(currentFieldIndex), fieldDocTree);
}
/**
* Build the comments for the field. Do nothing if
* {@link Configuration#nocomment} is set to true.
*
* @param node the XML element that specifies which components to document
* @param fieldDocTree the content tree to which the documentation will be added
*/
public void buildFieldComments(XMLNode node, Content fieldDocTree) {
if (!configuration.nocomment) {
writer.addComments((FieldDoc) fields.get(currentFieldIndex), fieldDocTree);
}
}
/**
* Build the tag information.
*
* @param node the XML element that specifies which components to document
* @param fieldDocTree the content tree to which the documentation will be added
*/
public void buildTagInfo(XMLNode node, Content fieldDocTree) {
writer.addTags((FieldDoc) fields.get(currentFieldIndex), fieldDocTree);
}
/**
* Return the field writer for this builder.
*
* @return the field writer for this builder.
*/
public FieldWriter getWriter() {
return writer;
}
}

129
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/LayoutParser.java Normal file
View File

@@ -0,0 +1,129 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.io.*;
import java.util.*;
import javax.xml.parsers.*;
import org.xml.sax.*;
import org.xml.sax.helpers.DefaultHandler;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* Parse the XML that specified the order of operation for the builders. This
* Parser uses SAX parsing.
*
* <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
* @since 1.5
* @see SAXParser
*/
public class LayoutParser extends DefaultHandler {
/**
* The map of XML elements that have been parsed.
*/
private Map<String,XMLNode> xmlElementsMap;
private XMLNode currentNode;
private final Configuration configuration;
private String currentRoot;
private boolean isParsing;
private LayoutParser(Configuration configuration) {
xmlElementsMap = new HashMap<String,XMLNode>();
this.configuration = configuration;
}
/**
* Return an instance of the BuilderXML.
*
* @param configuration the current configuration of the doclet.
* @return an instance of the BuilderXML.
*/
public static LayoutParser getInstance(Configuration configuration) {
return new LayoutParser(configuration);
}
/**
* Parse the XML specifying the layout of the documentation.
*
* @return the list of XML elements parsed.
*/
public XMLNode parseXML(String root) {
if (xmlElementsMap.containsKey(root)) {
return xmlElementsMap.get(root);
}
try {
currentRoot = root;
isParsing = false;
SAXParserFactory factory = SAXParserFactory.newInstance();
SAXParser saxParser = factory.newSAXParser();
InputStream in = configuration.getBuilderXML();
saxParser.parse(in, this);
return xmlElementsMap.get(root);
} catch (Throwable t) {
t.printStackTrace();
throw new DocletAbortException(t);
}
}
/**
* {@inheritDoc}
*/
@Override
public void startElement(String namespaceURI, String sName, String qName,
Attributes attrs)
throws SAXException {
if (isParsing || qName.equals(currentRoot)) {
isParsing = true;
currentNode = new XMLNode(currentNode, qName);
for (int i = 0; i < attrs.getLength(); i++)
currentNode.attrs.put(attrs.getLocalName(i), attrs.getValue(i));
if (qName.equals(currentRoot))
xmlElementsMap.put(qName, currentNode);
}
}
/**
* {@inheritDoc}
*/
@Override
public void endElement(String namespaceURI, String sName, String qName)
throws SAXException {
if (! isParsing) {
return;
}
currentNode = currentNode.parent;
isParsing = ! qName.equals(currentRoot);
}
}

532
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/MemberSummaryBuilder.java Normal file
View File

@@ -0,0 +1,532 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.util.*;
import java.text.MessageFormat;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* Builds the member summary.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public class MemberSummaryBuilder extends AbstractMemberBuilder {
/**
* The XML root for this builder.
*/
public static final String NAME = "MemberSummary";
/**
* The visible members for the given class.
*/
private final VisibleMemberMap[] visibleMemberMaps;
/**
* The member summary writers for the given class.
*/
private MemberSummaryWriter[] memberSummaryWriters;
/**
* The type being documented.
*/
private final ClassDoc classDoc;
/**
* Construct a new MemberSummaryBuilder.
*
* @param classWriter the writer for the class whose members are being
* summarized.
* @param context the build context.
*/
private MemberSummaryBuilder(Context context, ClassDoc classDoc) {
super(context);
this.classDoc = classDoc;
visibleMemberMaps =
new VisibleMemberMap[VisibleMemberMap.NUM_MEMBER_TYPES];
for (int i = 0; i < VisibleMemberMap.NUM_MEMBER_TYPES; i++) {
visibleMemberMaps[i] =
new VisibleMemberMap(
classDoc,
i,
configuration);
}
}
/**
* Construct a new MemberSummaryBuilder.
*
* @param classWriter the writer for the class whose members are being
* summarized.
* @param context the build context.
*/
public static MemberSummaryBuilder getInstance(
ClassWriter classWriter, Context context)
throws Exception {
MemberSummaryBuilder builder = new MemberSummaryBuilder(context,
classWriter.getClassDoc());
builder.memberSummaryWriters =
new MemberSummaryWriter[VisibleMemberMap.NUM_MEMBER_TYPES];
WriterFactory wf = context.configuration.getWriterFactory();
for (int i = 0; i < VisibleMemberMap.NUM_MEMBER_TYPES; i++) {
builder.memberSummaryWriters[i] =
builder.visibleMemberMaps[i].noVisibleMembers() ?
null :
wf.getMemberSummaryWriter(classWriter, i);
}
return builder;
}
/**
* Construct a new MemberSummaryBuilder.
*
* @param annotationTypeWriter the writer for the class whose members are
* being summarized.
* @param configuration the current configuration of the doclet.
*/
public static MemberSummaryBuilder getInstance(
AnnotationTypeWriter annotationTypeWriter, Context context)
throws Exception {
MemberSummaryBuilder builder = new MemberSummaryBuilder(context,
annotationTypeWriter.getAnnotationTypeDoc());
builder.memberSummaryWriters =
new MemberSummaryWriter[VisibleMemberMap.NUM_MEMBER_TYPES];
WriterFactory wf = context.configuration.getWriterFactory();
for (int i = 0; i < VisibleMemberMap.NUM_MEMBER_TYPES; i++) {
builder.memberSummaryWriters[i] =
builder.visibleMemberMaps[i].noVisibleMembers()?
null :
wf.getMemberSummaryWriter(
annotationTypeWriter, i);
}
return builder;
}
/**
* {@inheritDoc}
*/
public String getName() {
return NAME;
}
/**
* Return the specified visible member map.
*
* @param type the type of visible member map to return.
* @return the specified visible member map.
* @throws ArrayIndexOutOfBoundsException when the type is invalid.
* @see VisibleMemberMap
*/
public VisibleMemberMap getVisibleMemberMap(int type) {
return visibleMemberMaps[type];
}
/**
* Return the specified member summary writer.
*
* @param type the type of member summary writer to return.
* @return the specified member summary writer.
* @throws ArrayIndexOutOfBoundsException when the type is invalid.
* @see VisibleMemberMap
*/
public MemberSummaryWriter getMemberSummaryWriter(int type) {
return memberSummaryWriters[type];
}
/**
* Returns a list of methods that will be documented for the given class.
* This information can be used for doclet specific documentation
* generation.
*
* @param type the type of members to return.
* @return a list of methods that will be documented.
* @see VisibleMemberMap
*/
public List<ProgramElementDoc> members(int type) {
return visibleMemberMaps[type].getLeafClassMembers(configuration);
}
/**
* Return true it there are any members to summarize.
*
* @return true if there are any members to summarize.
*/
public boolean hasMembersToDocument() {
if (classDoc instanceof AnnotationTypeDoc) {
return ((AnnotationTypeDoc) classDoc).elements().length > 0;
}
for (int i = 0; i < VisibleMemberMap.NUM_MEMBER_TYPES; i++) {
VisibleMemberMap members = visibleMemberMaps[i];
if (!members.noVisibleMembers()) {
return true;
}
}
return false;
}
/**
* Build the summary for the enum constants.
*
* @param node the XML element that specifies which components to document
* @param memberSummaryTree the content tree to which the documentation will be added
*/
public void buildEnumConstantsSummary(XMLNode node, Content memberSummaryTree) {
MemberSummaryWriter writer =
memberSummaryWriters[VisibleMemberMap.ENUM_CONSTANTS];
VisibleMemberMap visibleMemberMap =
visibleMemberMaps[VisibleMemberMap.ENUM_CONSTANTS];
addSummary(writer, visibleMemberMap, false, memberSummaryTree);
}
/**
* Build the summary for fields.
*
* @param node the XML element that specifies which components to document
* @param memberSummaryTree the content tree to which the documentation will be added
*/
public void buildAnnotationTypeFieldsSummary(XMLNode node, Content memberSummaryTree) {
MemberSummaryWriter writer =
memberSummaryWriters[VisibleMemberMap.ANNOTATION_TYPE_FIELDS];
VisibleMemberMap visibleMemberMap =
visibleMemberMaps[VisibleMemberMap.ANNOTATION_TYPE_FIELDS];
addSummary(writer, visibleMemberMap, false, memberSummaryTree);
}
/**
* Build the summary for the optional members.
*
* @param node the XML element that specifies which components to document
* @param memberSummaryTree the content tree to which the documentation will be added
*/
public void buildAnnotationTypeOptionalMemberSummary(XMLNode node, Content memberSummaryTree) {
MemberSummaryWriter writer =
memberSummaryWriters[VisibleMemberMap.ANNOTATION_TYPE_MEMBER_OPTIONAL];
VisibleMemberMap visibleMemberMap =
visibleMemberMaps[VisibleMemberMap.ANNOTATION_TYPE_MEMBER_OPTIONAL];
addSummary(writer, visibleMemberMap, false, memberSummaryTree);
}
/**
* Build the summary for the optional members.
*
* @param node the XML element that specifies which components to document
* @param memberSummaryTree the content tree to which the documentation will be added
*/
public void buildAnnotationTypeRequiredMemberSummary(XMLNode node, Content memberSummaryTree) {
MemberSummaryWriter writer =
memberSummaryWriters[VisibleMemberMap.ANNOTATION_TYPE_MEMBER_REQUIRED];
VisibleMemberMap visibleMemberMap =
visibleMemberMaps[VisibleMemberMap.ANNOTATION_TYPE_MEMBER_REQUIRED];
addSummary(writer, visibleMemberMap, false, memberSummaryTree);
}
/**
* Build the summary for the fields.
*
* @param node the XML element that specifies which components to document
* @param memberSummaryTree the content tree to which the documentation will be added
*/
public void buildFieldsSummary(XMLNode node, Content memberSummaryTree) {
MemberSummaryWriter writer =
memberSummaryWriters[VisibleMemberMap.FIELDS];
VisibleMemberMap visibleMemberMap =
visibleMemberMaps[VisibleMemberMap.FIELDS];
addSummary(writer, visibleMemberMap, true, memberSummaryTree);
}
/**
* Build the summary for the fields.
*/
public void buildPropertiesSummary(XMLNode node, Content memberSummaryTree) {
MemberSummaryWriter writer =
memberSummaryWriters[VisibleMemberMap.PROPERTIES];
VisibleMemberMap visibleMemberMap =
visibleMemberMaps[VisibleMemberMap.PROPERTIES];
addSummary(writer, visibleMemberMap, true, memberSummaryTree);
}
/**
* Build the summary for the nested classes.
*
* @param node the XML element that specifies which components to document
* @param memberSummaryTree the content tree to which the documentation will be added
*/
public void buildNestedClassesSummary(XMLNode node, Content memberSummaryTree) {
MemberSummaryWriter writer =
memberSummaryWriters[VisibleMemberMap.INNERCLASSES];
VisibleMemberMap visibleMemberMap =
visibleMemberMaps[VisibleMemberMap.INNERCLASSES];
addSummary(writer, visibleMemberMap, true, memberSummaryTree);
}
/**
* Build the method summary.
*
* @param node the XML element that specifies which components to document
* @param memberSummaryTree the content tree to which the documentation will be added
*/
public void buildMethodsSummary(XMLNode node, Content memberSummaryTree) {
MemberSummaryWriter writer =
memberSummaryWriters[VisibleMemberMap.METHODS];
VisibleMemberMap visibleMemberMap =
visibleMemberMaps[VisibleMemberMap.METHODS];
addSummary(writer, visibleMemberMap, true, memberSummaryTree);
}
/**
* Build the constructor summary.
*
* @param node the XML element that specifies which components to document
* @param memberSummaryTree the content tree to which the documentation will be added
*/
public void buildConstructorsSummary(XMLNode node, Content memberSummaryTree) {
MemberSummaryWriter writer =
memberSummaryWriters[VisibleMemberMap.CONSTRUCTORS];
VisibleMemberMap visibleMemberMap =
visibleMemberMaps[VisibleMemberMap.CONSTRUCTORS];
addSummary(writer, visibleMemberMap, false, memberSummaryTree);
}
/**
* Build the member summary for the given members.
*
* @param writer the summary writer to write the output.
* @param visibleMemberMap the given members to summarize.
* @param summaryTreeList list of content trees to which the documentation will be added
*/
private void buildSummary(MemberSummaryWriter writer,
VisibleMemberMap visibleMemberMap, LinkedList<Content> summaryTreeList) {
List<ProgramElementDoc> members = new ArrayList<ProgramElementDoc>(visibleMemberMap.getLeafClassMembers(
configuration));
if (members.size() > 0) {
Collections.sort(members);
List<Content> tableContents = new LinkedList<Content>();
for (int i = 0; i < members.size(); i++) {
ProgramElementDoc member = members.get(i);
final ProgramElementDoc propertyDoc =
visibleMemberMap.getPropertyMemberDoc(member);
if (propertyDoc != null) {
processProperty(visibleMemberMap, member, propertyDoc);
}
Tag[] firstSentenceTags = member.firstSentenceTags();
if (member instanceof MethodDoc && firstSentenceTags.length == 0) {
//Inherit comments from overriden or implemented method if
//necessary.
DocFinder.Output inheritedDoc =
DocFinder.search(new DocFinder.Input((MethodDoc) member));
if (inheritedDoc.holder != null
&& inheritedDoc.holder.firstSentenceTags().length > 0) {
firstSentenceTags = inheritedDoc.holder.firstSentenceTags();
}
}
writer.addMemberSummary(classDoc, member, firstSentenceTags,
tableContents, i);
}
summaryTreeList.add(writer.getSummaryTableTree(classDoc, tableContents));
}
}
/**
* Process the property method, property setter and/or property getter
* comment text so that it contains the documentation from
* the property field. The method adds the leading sentence,
* copied documentation including the defaultValue tag and
* the see tags if the appropriate property getter and setter are
* available.
*
* @param visibleMemberMap the members information.
* @param member the member which is to be augmented.
* @param propertyDoc the original property documentation.
*/
private void processProperty(VisibleMemberMap visibleMemberMap,
ProgramElementDoc member,
ProgramElementDoc propertyDoc) {
StringBuilder commentTextBuilder = new StringBuilder();
final boolean isSetter = isSetter(member);
final boolean isGetter = isGetter(member);
if (isGetter || isSetter) {
//add "[GS]ets the value of the property PROPERTY_NAME."
if (isSetter) {
commentTextBuilder.append(
MessageFormat.format(
configuration.getText("doclet.PropertySetterWithName"),
Util.propertyNameFromMethodName(configuration, member.name())));
}
if (isGetter) {
commentTextBuilder.append(
MessageFormat.format(
configuration.getText("doclet.PropertyGetterWithName"),
Util.propertyNameFromMethodName(configuration, member.name())));
}
if (propertyDoc.commentText() != null
&& !propertyDoc.commentText().isEmpty()) {
commentTextBuilder.append(" \n @propertyDescription ");
}
}
commentTextBuilder.append(propertyDoc.commentText());
// copy certain tags
List<Tag> allTags = new LinkedList<Tag>();
String[] tagNames = {"@defaultValue", "@since"};
for (String tagName: tagNames) {
Tag[] tags = propertyDoc.tags(tagName);
if (tags != null) {
allTags.addAll(Arrays.asList(tags));
}
}
for (Tag tag: allTags) {
commentTextBuilder.append("\n")
.append(tag.name())
.append(" ")
.append(tag.text());
}
//add @see tags
if (!isGetter && !isSetter) {
MethodDoc getter = (MethodDoc) visibleMemberMap.getGetterForProperty(member);
MethodDoc setter = (MethodDoc) visibleMemberMap.getSetterForProperty(member);
if ((null != getter)
&& (commentTextBuilder.indexOf("@see #" + getter.name()) == -1)) {
commentTextBuilder.append("\n @see #")
.append(getter.name())
.append("() ");
}
if ((null != setter)
&& (commentTextBuilder.indexOf("@see #" + setter.name()) == -1)) {
String typeName = setter.parameters()[0].typeName();
// Removal of type parameters and package information.
typeName = typeName.split("<")[0];
if (typeName.contains(".")) {
typeName = typeName.substring(typeName.lastIndexOf(".") + 1);
}
commentTextBuilder.append("\n @see #").append(setter.name());
if (setter.parameters()[0].type().asTypeVariable() == null) {
commentTextBuilder.append("(").append(typeName).append(")");
}
commentTextBuilder.append(" \n");
}
}
member.setRawCommentText(commentTextBuilder.toString());
}
/**
* Test whether the method is a getter.
* @param ped property method documentation. Needs to be either property
* method, property getter, or property setter.
* @return true if the given documentation belongs to a getter.
*/
private boolean isGetter(ProgramElementDoc ped) {
final String pedName = ped.name();
return pedName.startsWith("get") || pedName.startsWith("is");
}
/**
* Test whether the method is a setter.
* @param ped property method documentation. Needs to be either property
* method, property getter, or property setter.
* @return true if the given documentation belongs to a setter.
*/
private boolean isSetter(ProgramElementDoc ped) {
return ped.name().startsWith("set");
}
/**
* Build the inherited member summary for the given methods.
*
* @param writer the writer for this member summary.
* @param visibleMemberMap the map for the members to document.
* @param summaryTreeList list of content trees to which the documentation will be added
*/
private void buildInheritedSummary(MemberSummaryWriter writer,
VisibleMemberMap visibleMemberMap, LinkedList<Content> summaryTreeList) {
for (Iterator<ClassDoc> iter = visibleMemberMap.getVisibleClassesList().iterator();
iter.hasNext();) {
ClassDoc inhclass = iter.next();
if (! (inhclass.isPublic() ||
Util.isLinkable(inhclass, configuration))) {
continue;
}
if (inhclass == classDoc) {
continue;
}
List<ProgramElementDoc> inhmembers = visibleMemberMap.getMembersFor(inhclass);
if (inhmembers.size() > 0) {
Collections.sort(inhmembers);
Content inheritedTree = writer.getInheritedSummaryHeader(inhclass);
Content linksTree = writer.getInheritedSummaryLinksTree();
for (int j = 0; j < inhmembers.size(); ++j) {
writer.addInheritedMemberSummary(
inhclass.isPackagePrivate() &&
! Util.isLinkable(inhclass, configuration) ?
classDoc : inhclass,
inhmembers.get(j),
j == 0,
j == inhmembers.size() - 1, linksTree);
}
inheritedTree.addContent(linksTree);
summaryTreeList.add(writer.getMemberTree(inheritedTree));
}
}
}
/**
* Add the summary for the documentation.
*
* @param writer the writer for this member summary.
* @param visibleMemberMap the map for the members to document.
* @param showInheritedSummary true if inherited summary should be documented
* @param memberSummaryTree the content tree to which the documentation will be added
*/
private void addSummary(MemberSummaryWriter writer,
VisibleMemberMap visibleMemberMap, boolean showInheritedSummary,
Content memberSummaryTree) {
LinkedList<Content> summaryTreeList = new LinkedList<Content>();
buildSummary(writer, visibleMemberMap, summaryTreeList);
if (showInheritedSummary)
buildInheritedSummary(writer, visibleMemberMap, summaryTreeList);
if (!summaryTreeList.isEmpty()) {
Content memberTree = writer.getMemberSummaryHeader(
classDoc, memberSummaryTree);
for (int i = 0; i < summaryTreeList.size(); i++) {
memberTree.addContent(summaryTreeList.get(i));
}
memberSummaryTree.addContent(writer.getMemberTree(memberTree));
}
}
}

242
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/MethodBuilder.java Normal file
View File

@@ -0,0 +1,242 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* Builds documentation for a method.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public class MethodBuilder extends AbstractMemberBuilder {
/**
* The index of the current field that is being documented at this point
* in time.
*/
private int currentMethodIndex;
/**
* The class whose methods are being documented.
*/
private final ClassDoc classDoc;
/**
* The visible methods for the given class.
*/
private final VisibleMemberMap visibleMemberMap;
/**
* The writer to output the method documentation.
*/
private final MethodWriter writer;
/**
* The methods being documented.
*/
private List<ProgramElementDoc> methods;
/**
* Construct a new MethodBuilder.
*
* @param context the build context.
* @param classDoc the class whoses members are being documented.
* @param writer the doclet specific writer.
*/
private MethodBuilder(Context context,
ClassDoc classDoc,
MethodWriter writer) {
super(context);
this.classDoc = classDoc;
this.writer = writer;
visibleMemberMap = new VisibleMemberMap(
classDoc,
VisibleMemberMap.METHODS,
configuration);
methods =
new ArrayList<ProgramElementDoc>(visibleMemberMap.getLeafClassMembers(
configuration));
if (configuration.getMemberComparator() != null) {
Collections.sort(methods, configuration.getMemberComparator());
}
}
/**
* Construct a new MethodBuilder.
*
* @param context the build context.
* @param classDoc the class whoses members are being documented.
* @param writer the doclet specific writer.
*
* @return an instance of a MethodBuilder.
*/
public static MethodBuilder getInstance(Context context,
ClassDoc classDoc, MethodWriter writer) {
return new MethodBuilder(context, classDoc, writer);
}
/**
* {@inheritDoc}
*/
public String getName() {
return "MethodDetails";
}
/**
* Returns a list of methods that will be documented for the given class.
* This information can be used for doclet specific documentation
* generation.
*
* @param classDoc the {@link ClassDoc} we want to check.
* @return a list of methods that will be documented.
*/
public List<ProgramElementDoc> members(ClassDoc classDoc) {
return visibleMemberMap.getMembersFor(classDoc);
}
/**
* Returns the visible member map for the methods of this class.
*
* @return the visible member map for the methods of this class.
*/
public VisibleMemberMap getVisibleMemberMap() {
return visibleMemberMap;
}
/**
* {@inheritDoc}
*/
public boolean hasMembersToDocument() {
return methods.size() > 0;
}
/**
* Build the method documentation.
*
* @param node the XML element that specifies which components to document
* @param memberDetailsTree the content tree to which the documentation will be added
*/
public void buildMethodDoc(XMLNode node, Content memberDetailsTree) {
if (writer == null) {
return;
}
int size = methods.size();
if (size > 0) {
Content methodDetailsTree = writer.getMethodDetailsTreeHeader(
classDoc, memberDetailsTree);
for (currentMethodIndex = 0; currentMethodIndex < size;
currentMethodIndex++) {
Content methodDocTree = writer.getMethodDocTreeHeader(
(MethodDoc) methods.get(currentMethodIndex),
methodDetailsTree);
buildChildren(node, methodDocTree);
methodDetailsTree.addContent(writer.getMethodDoc(
methodDocTree, (currentMethodIndex == size - 1)));
}
memberDetailsTree.addContent(
writer.getMethodDetails(methodDetailsTree));
}
}
/**
* Build the signature.
*
* @param node the XML element that specifies which components to document
* @param methodDocTree the content tree to which the documentation will be added
*/
public void buildSignature(XMLNode node, Content methodDocTree) {
methodDocTree.addContent(
writer.getSignature((MethodDoc) methods.get(currentMethodIndex)));
}
/**
* Build the deprecation information.
*
* @param node the XML element that specifies which components to document
* @param methodDocTree the content tree to which the documentation will be added
*/
public void buildDeprecationInfo(XMLNode node, Content methodDocTree) {
writer.addDeprecated(
(MethodDoc) methods.get(currentMethodIndex), methodDocTree);
}
/**
* Build the comments for the method. Do nothing if
* {@link Configuration#nocomment} is set to true.
*
* @param node the XML element that specifies which components to document
* @param methodDocTree the content tree to which the documentation will be added
*/
public void buildMethodComments(XMLNode node, Content methodDocTree) {
if (!configuration.nocomment) {
MethodDoc method = (MethodDoc) methods.get(currentMethodIndex);
if (method.inlineTags().length == 0) {
DocFinder.Output docs = DocFinder.search(
new DocFinder.Input(method));
method = docs.inlineTags != null && docs.inlineTags.length > 0 ?
(MethodDoc) docs.holder : method;
}
//NOTE: When we fix the bug where ClassDoc.interfaceTypes() does
// not pass all implemented interfaces, holder will be the
// interface type. For now, it is really the erasure.
writer.addComments(method.containingClass(), method, methodDocTree);
}
}
/**
* Build the tag information.
*
* @param node the XML element that specifies which components to document
* @param methodDocTree the content tree to which the documentation will be added
*/
public void buildTagInfo(XMLNode node, Content methodDocTree) {
writer.addTags((MethodDoc) methods.get(currentMethodIndex),
methodDocTree);
}
/**
* Return the method writer for this builder.
*
* @return the method writer for this builder.
*/
public MethodWriter getWriter() {
return writer;
}
}

364
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/PackageSummaryBuilder.java Normal file
View File

@@ -0,0 +1,364 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.io.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* Builds the summary for a given package.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public class PackageSummaryBuilder extends AbstractBuilder {
/**
* The root element of the package summary XML is {@value}.
*/
public static final String ROOT = "PackageDoc";
/**
* The package being documented.
*/
private final PackageDoc packageDoc;
/**
* The doclet specific writer that will output the result.
*/
private final PackageSummaryWriter packageWriter;
/**
* The content that will be added to the package summary documentation tree.
*/
private Content contentTree;
/**
* Construct a new PackageSummaryBuilder.
*
* @param context the build context.
* @param pkg the package being documented.
* @param packageWriter the doclet specific writer that will output the
* result.
*/
private PackageSummaryBuilder(Context context,
PackageDoc pkg,
PackageSummaryWriter packageWriter) {
super(context);
this.packageDoc = pkg;
this.packageWriter = packageWriter;
}
/**
* Construct a new PackageSummaryBuilder.
*
* @param context the build context.
* @param pkg the package being documented.
* @param packageWriter the doclet specific writer that will output the
* result.
*
* @return an instance of a PackageSummaryBuilder.
*/
public static PackageSummaryBuilder getInstance(Context context,
PackageDoc pkg, PackageSummaryWriter packageWriter) {
return new PackageSummaryBuilder(context, pkg, packageWriter);
}
/**
* Build the package summary.
*/
public void build() throws IOException {
if (packageWriter == null) {
//Doclet does not support this output.
return;
}
build(layoutParser.parseXML(ROOT), contentTree);
}
/**
* {@inheritDoc}
*/
public String getName() {
return ROOT;
}
/**
* Build the package documentation.
*
* @param node the XML element that specifies which components to document
* @param contentTree the content tree to which the documentation will be added
*/
public void buildPackageDoc(XMLNode node, Content contentTree) throws Exception {
contentTree = packageWriter.getPackageHeader(Util.getPackageName(packageDoc));
buildChildren(node, contentTree);
packageWriter.addPackageFooter(contentTree);
packageWriter.printDocument(contentTree);
packageWriter.close();
Util.copyDocFiles(configuration, packageDoc);
}
/**
* Build the content for the package doc.
*
* @param node the XML element that specifies which components to document
* @param contentTree the content tree to which the package contents
* will be added
*/
public void buildContent(XMLNode node, Content contentTree) {
Content packageContentTree = packageWriter.getContentHeader();
buildChildren(node, packageContentTree);
contentTree.addContent(packageContentTree);
}
/**
* Build the package summary.
*
* @param node the XML element that specifies which components to document
* @param packageContentTree the package content tree to which the summaries will
* be added
*/
public void buildSummary(XMLNode node, Content packageContentTree) {
Content summaryContentTree = packageWriter.getSummaryHeader();
buildChildren(node, summaryContentTree);
packageContentTree.addContent(summaryContentTree);
}
/**
* Build the summary for the interfaces in this package.
*
* @param node the XML element that specifies which components to document
* @param summaryContentTree the summary tree to which the interface summary
* will be added
*/
public void buildInterfaceSummary(XMLNode node, Content summaryContentTree) {
String interfaceTableSummary =
configuration.getText("doclet.Member_Table_Summary",
configuration.getText("doclet.Interface_Summary"),
configuration.getText("doclet.interfaces"));
String[] interfaceTableHeader = new String[] {
configuration.getText("doclet.Interface"),
configuration.getText("doclet.Description")
};
ClassDoc[] interfaces =
packageDoc.isIncluded()
? packageDoc.interfaces()
: configuration.classDocCatalog.interfaces(
Util.getPackageName(packageDoc));
interfaces = Util.filterOutPrivateClasses(interfaces, configuration.javafx);
if (interfaces.length > 0) {
packageWriter.addClassesSummary(
interfaces,
configuration.getText("doclet.Interface_Summary"),
interfaceTableSummary, interfaceTableHeader, summaryContentTree);
}
}
/**
* Build the summary for the classes in this package.
*
* @param node the XML element that specifies which components to document
* @param summaryContentTree the summary tree to which the class summary will
* be added
*/
public void buildClassSummary(XMLNode node, Content summaryContentTree) {
String classTableSummary =
configuration.getText("doclet.Member_Table_Summary",
configuration.getText("doclet.Class_Summary"),
configuration.getText("doclet.classes"));
String[] classTableHeader = new String[] {
configuration.getText("doclet.Class"),
configuration.getText("doclet.Description")
};
ClassDoc[] classes =
packageDoc.isIncluded()
? packageDoc.ordinaryClasses()
: configuration.classDocCatalog.ordinaryClasses(
Util.getPackageName(packageDoc));
classes = Util.filterOutPrivateClasses(classes, configuration.javafx);
if (classes.length > 0) {
packageWriter.addClassesSummary(
classes,
configuration.getText("doclet.Class_Summary"),
classTableSummary, classTableHeader, summaryContentTree);
}
}
/**
* Build the summary for the enums in this package.
*
* @param node the XML element that specifies which components to document
* @param summaryContentTree the summary tree to which the enum summary will
* be added
*/
public void buildEnumSummary(XMLNode node, Content summaryContentTree) {
String enumTableSummary =
configuration.getText("doclet.Member_Table_Summary",
configuration.getText("doclet.Enum_Summary"),
configuration.getText("doclet.enums"));
String[] enumTableHeader = new String[] {
configuration.getText("doclet.Enum"),
configuration.getText("doclet.Description")
};
ClassDoc[] enums =
packageDoc.isIncluded()
? packageDoc.enums()
: configuration.classDocCatalog.enums(
Util.getPackageName(packageDoc));
enums = Util.filterOutPrivateClasses(enums, configuration.javafx);
if (enums.length > 0) {
packageWriter.addClassesSummary(
enums,
configuration.getText("doclet.Enum_Summary"),
enumTableSummary, enumTableHeader, summaryContentTree);
}
}
/**
* Build the summary for the exceptions in this package.
*
* @param node the XML element that specifies which components to document
* @param summaryContentTree the summary tree to which the exception summary will
* be added
*/
public void buildExceptionSummary(XMLNode node, Content summaryContentTree) {
String exceptionTableSummary =
configuration.getText("doclet.Member_Table_Summary",
configuration.getText("doclet.Exception_Summary"),
configuration.getText("doclet.exceptions"));
String[] exceptionTableHeader = new String[] {
configuration.getText("doclet.Exception"),
configuration.getText("doclet.Description")
};
ClassDoc[] exceptions =
packageDoc.isIncluded()
? packageDoc.exceptions()
: configuration.classDocCatalog.exceptions(
Util.getPackageName(packageDoc));
exceptions = Util.filterOutPrivateClasses(exceptions, configuration.javafx);
if (exceptions.length > 0) {
packageWriter.addClassesSummary(
exceptions,
configuration.getText("doclet.Exception_Summary"),
exceptionTableSummary, exceptionTableHeader, summaryContentTree);
}
}
/**
* Build the summary for the errors in this package.
*
* @param node the XML element that specifies which components to document
* @param summaryContentTree the summary tree to which the error summary will
* be added
*/
public void buildErrorSummary(XMLNode node, Content summaryContentTree) {
String errorTableSummary =
configuration.getText("doclet.Member_Table_Summary",
configuration.getText("doclet.Error_Summary"),
configuration.getText("doclet.errors"));
String[] errorTableHeader = new String[] {
configuration.getText("doclet.Error"),
configuration.getText("doclet.Description")
};
ClassDoc[] errors =
packageDoc.isIncluded()
? packageDoc.errors()
: configuration.classDocCatalog.errors(
Util.getPackageName(packageDoc));
errors = Util.filterOutPrivateClasses(errors, configuration.javafx);
if (errors.length > 0) {
packageWriter.addClassesSummary(
errors,
configuration.getText("doclet.Error_Summary"),
errorTableSummary, errorTableHeader, summaryContentTree);
}
}
/**
* Build the summary for the annotation type in this package.
*
* @param node the XML element that specifies which components to document
* @param summaryContentTree the summary tree to which the annotation type
* summary will be added
*/
public void buildAnnotationTypeSummary(XMLNode node, Content summaryContentTree) {
String annotationtypeTableSummary =
configuration.getText("doclet.Member_Table_Summary",
configuration.getText("doclet.Annotation_Types_Summary"),
configuration.getText("doclet.annotationtypes"));
String[] annotationtypeTableHeader = new String[] {
configuration.getText("doclet.AnnotationType"),
configuration.getText("doclet.Description")
};
ClassDoc[] annotationTypes =
packageDoc.isIncluded()
? packageDoc.annotationTypes()
: configuration.classDocCatalog.annotationTypes(
Util.getPackageName(packageDoc));
annotationTypes = Util.filterOutPrivateClasses(annotationTypes, configuration.javafx);
if (annotationTypes.length > 0) {
packageWriter.addClassesSummary(
annotationTypes,
configuration.getText("doclet.Annotation_Types_Summary"),
annotationtypeTableSummary, annotationtypeTableHeader,
summaryContentTree);
}
}
/**
* Build the description of the summary.
*
* @param node the XML element that specifies which components to document
* @param packageContentTree the tree to which the package description will
* be added
*/
public void buildPackageDescription(XMLNode node, Content packageContentTree) {
if (configuration.nocomment) {
return;
}
packageWriter.addPackageDescription(packageContentTree);
}
/**
* Build the tags of the summary.
*
* @param node the XML element that specifies which components to document
* @param packageContentTree the tree to which the package tags will be added
*/
public void buildPackageTags(XMLNode node, Content packageContentTree) {
if (configuration.nocomment) {
return;
}
packageWriter.addPackageTags(packageContentTree);
}
}

374
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/ProfilePackageSummaryBuilder.java Normal file
View File

@@ -0,0 +1,374 @@
/*
* Copyright (c) 2013, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.io.*;
import com.sun.javadoc.*;
import com.sun.tools.javac.jvm.Profile;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* Builds the summary for a given profile package.
*
* <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 Bhavesh Patel
*/
public class ProfilePackageSummaryBuilder extends AbstractBuilder {
/**
* The root element of the profile package summary XML is {@value}.
*/
public static final String ROOT = "PackageDoc";
/**
* The profile package being documented.
*/
private final PackageDoc packageDoc;
/**
* The name of the profile being documented.
*/
private final String profileName;
/**
* The value of the profile being documented.
*/
private final int profileValue;
/**
* The doclet specific writer that will output the result.
*/
private final ProfilePackageSummaryWriter profilePackageWriter;
/**
* The content that will be added to the profile package summary documentation tree.
*/
private Content contentTree;
/**
* Construct a new ProfilePackageSummaryBuilder.
*
* @param context the build context.
* @param pkg the profile package being documented.
* @param profilePackageWriter the doclet specific writer that will output the
* result.
* @param profile the profile being documented.
*/
private ProfilePackageSummaryBuilder(Context context,
PackageDoc pkg, ProfilePackageSummaryWriter profilePackageWriter,
Profile profile) {
super(context);
this.packageDoc = pkg;
this.profilePackageWriter = profilePackageWriter;
this.profileName = profile.name;
this.profileValue = profile.value;
}
/**
* Construct a new ProfilePackageSummaryBuilder.
*
* @param context the build context.
* @param pkg the profile package being documented.
* @param profilePackageWriter the doclet specific writer that will output the
* result.
* @param profile the profile being documented.
*
* @return an instance of a ProfilePackageSummaryBuilder.
*/
public static ProfilePackageSummaryBuilder getInstance(Context context,
PackageDoc pkg, ProfilePackageSummaryWriter profilePackageWriter,
Profile profile) {
return new ProfilePackageSummaryBuilder(context, pkg, profilePackageWriter,
profile);
}
/**
* Build the profile package summary.
*/
public void build() throws IOException {
if (profilePackageWriter == null) {
//Doclet does not support this output.
return;
}
build(layoutParser.parseXML(ROOT), contentTree);
}
/**
* {@inheritDoc}
*/
public String getName() {
return ROOT;
}
/**
* Build the profile package documentation.
*
* @param node the XML element that specifies which components to document
* @param contentTree the content tree to which the documentation will be added
*/
public void buildPackageDoc(XMLNode node, Content contentTree) throws Exception {
contentTree = profilePackageWriter.getPackageHeader(
Util.getPackageName(packageDoc));
buildChildren(node, contentTree);
profilePackageWriter.addPackageFooter(contentTree);
profilePackageWriter.printDocument(contentTree);
profilePackageWriter.close();
Util.copyDocFiles(configuration, packageDoc);
}
/**
* Build the content for the profile package doc.
*
* @param node the XML element that specifies which components to document
* @param contentTree the content tree to which the package contents
* will be added
*/
public void buildContent(XMLNode node, Content contentTree) {
Content packageContentTree = profilePackageWriter.getContentHeader();
buildChildren(node, packageContentTree);
contentTree.addContent(packageContentTree);
}
/**
* Build the profile package summary.
*
* @param node the XML element that specifies which components to document
* @param packageContentTree the package content tree to which the summaries will
* be added
*/
public void buildSummary(XMLNode node, Content packageContentTree) {
Content summaryContentTree = profilePackageWriter.getSummaryHeader();
buildChildren(node, summaryContentTree);
packageContentTree.addContent(summaryContentTree);
}
/**
* Build the summary for the interfaces in this package.
*
* @param node the XML element that specifies which components to document
* @param summaryContentTree the summary tree to which the interface summary
* will be added
*/
public void buildInterfaceSummary(XMLNode node, Content summaryContentTree) {
String interfaceTableSummary =
configuration.getText("doclet.Member_Table_Summary",
configuration.getText("doclet.Interface_Summary"),
configuration.getText("doclet.interfaces"));
String[] interfaceTableHeader = new String[] {
configuration.getText("doclet.Interface"),
configuration.getText("doclet.Description")
};
ClassDoc[] interfaces =
packageDoc.isIncluded()
? packageDoc.interfaces()
: configuration.classDocCatalog.interfaces(
Util.getPackageName(packageDoc));
if (interfaces.length > 0) {
profilePackageWriter.addClassesSummary(
interfaces,
configuration.getText("doclet.Interface_Summary"),
interfaceTableSummary, interfaceTableHeader, summaryContentTree);
}
}
/**
* Build the summary for the classes in this package.
*
* @param node the XML element that specifies which components to document
* @param summaryContentTree the summary tree to which the class summary will
* be added
*/
public void buildClassSummary(XMLNode node, Content summaryContentTree) {
String classTableSummary =
configuration.getText("doclet.Member_Table_Summary",
configuration.getText("doclet.Class_Summary"),
configuration.getText("doclet.classes"));
String[] classTableHeader = new String[] {
configuration.getText("doclet.Class"),
configuration.getText("doclet.Description")
};
ClassDoc[] classes =
packageDoc.isIncluded()
? packageDoc.ordinaryClasses()
: configuration.classDocCatalog.ordinaryClasses(
Util.getPackageName(packageDoc));
if (classes.length > 0) {
profilePackageWriter.addClassesSummary(
classes,
configuration.getText("doclet.Class_Summary"),
classTableSummary, classTableHeader, summaryContentTree);
}
}
/**
* Build the summary for the enums in this package.
*
* @param node the XML element that specifies which components to document
* @param summaryContentTree the summary tree to which the enum summary will
* be added
*/
public void buildEnumSummary(XMLNode node, Content summaryContentTree) {
String enumTableSummary =
configuration.getText("doclet.Member_Table_Summary",
configuration.getText("doclet.Enum_Summary"),
configuration.getText("doclet.enums"));
String[] enumTableHeader = new String[] {
configuration.getText("doclet.Enum"),
configuration.getText("doclet.Description")
};
ClassDoc[] enums =
packageDoc.isIncluded()
? packageDoc.enums()
: configuration.classDocCatalog.enums(
Util.getPackageName(packageDoc));
if (enums.length > 0) {
profilePackageWriter.addClassesSummary(
enums,
configuration.getText("doclet.Enum_Summary"),
enumTableSummary, enumTableHeader, summaryContentTree);
}
}
/**
* Build the summary for the exceptions in this package.
*
* @param node the XML element that specifies which components to document
* @param summaryContentTree the summary tree to which the exception summary will
* be added
*/
public void buildExceptionSummary(XMLNode node, Content summaryContentTree) {
String exceptionTableSummary =
configuration.getText("doclet.Member_Table_Summary",
configuration.getText("doclet.Exception_Summary"),
configuration.getText("doclet.exceptions"));
String[] exceptionTableHeader = new String[] {
configuration.getText("doclet.Exception"),
configuration.getText("doclet.Description")
};
ClassDoc[] exceptions =
packageDoc.isIncluded()
? packageDoc.exceptions()
: configuration.classDocCatalog.exceptions(
Util.getPackageName(packageDoc));
if (exceptions.length > 0) {
profilePackageWriter.addClassesSummary(
exceptions,
configuration.getText("doclet.Exception_Summary"),
exceptionTableSummary, exceptionTableHeader, summaryContentTree);
}
}
/**
* Build the summary for the errors in this package.
*
* @param node the XML element that specifies which components to document
* @param summaryContentTree the summary tree to which the error summary will
* be added
*/
public void buildErrorSummary(XMLNode node, Content summaryContentTree) {
String errorTableSummary =
configuration.getText("doclet.Member_Table_Summary",
configuration.getText("doclet.Error_Summary"),
configuration.getText("doclet.errors"));
String[] errorTableHeader = new String[] {
configuration.getText("doclet.Error"),
configuration.getText("doclet.Description")
};
ClassDoc[] errors =
packageDoc.isIncluded()
? packageDoc.errors()
: configuration.classDocCatalog.errors(
Util.getPackageName(packageDoc));
if (errors.length > 0) {
profilePackageWriter.addClassesSummary(
errors,
configuration.getText("doclet.Error_Summary"),
errorTableSummary, errorTableHeader, summaryContentTree);
}
}
/**
* Build the summary for the annotation type in this package.
*
* @param node the XML element that specifies which components to document
* @param summaryContentTree the summary tree to which the annotation type
* summary will be added
*/
public void buildAnnotationTypeSummary(XMLNode node, Content summaryContentTree) {
String annotationtypeTableSummary =
configuration.getText("doclet.Member_Table_Summary",
configuration.getText("doclet.Annotation_Types_Summary"),
configuration.getText("doclet.annotationtypes"));
String[] annotationtypeTableHeader = new String[] {
configuration.getText("doclet.AnnotationType"),
configuration.getText("doclet.Description")
};
ClassDoc[] annotationTypes =
packageDoc.isIncluded()
? packageDoc.annotationTypes()
: configuration.classDocCatalog.annotationTypes(
Util.getPackageName(packageDoc));
if (annotationTypes.length > 0) {
profilePackageWriter.addClassesSummary(
annotationTypes,
configuration.getText("doclet.Annotation_Types_Summary"),
annotationtypeTableSummary, annotationtypeTableHeader,
summaryContentTree);
}
}
/**
* Build the description of the summary.
*
* @param node the XML element that specifies which components to document
* @param packageContentTree the tree to which the package description will
* be added
*/
public void buildPackageDescription(XMLNode node, Content packageContentTree) {
if (configuration.nocomment) {
return;
}
profilePackageWriter.addPackageDescription(packageContentTree);
}
/**
* Build the tags of the summary.
*
* @param node the XML element that specifies which components to document
* @param packageContentTree the tree to which the package tags will be added
*/
public void buildPackageTags(XMLNode node, Content packageContentTree) {
if (configuration.nocomment) {
return;
}
profilePackageWriter.addPackageTags(packageContentTree);
}
}

328
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/ProfileSummaryBuilder.java Normal file
View File

@@ -0,0 +1,328 @@
/*
* Copyright (c) 2013, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.io.*;
import com.sun.javadoc.*;
import com.sun.tools.javac.jvm.Profile;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* Builds the summary for a given profile.
*
* <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 Bhavesh Patel
*/
public class ProfileSummaryBuilder extends AbstractBuilder {
/**
* The root element of the profile summary XML is {@value}.
*/
public static final String ROOT = "ProfileDoc";
/**
* The profile being documented.
*/
private final Profile profile;
/**
* The doclet specific writer that will output the result.
*/
private final ProfileSummaryWriter profileWriter;
/**
* The content that will be added to the profile summary documentation tree.
*/
private Content contentTree;
/**
* The profile package being documented.
*/
private PackageDoc pkg;
/**
* Construct a new ProfileSummaryBuilder.
*
* @param context the build context.
* @param profile the profile being documented.
* @param profileWriter the doclet specific writer that will output the
* result.
*/
private ProfileSummaryBuilder(Context context,
Profile profile, ProfileSummaryWriter profileWriter) {
super(context);
this.profile = profile;
this.profileWriter = profileWriter;
}
/**
* Construct a new ProfileSummaryBuilder.
*
* @param context the build context.
* @param profile the profile being documented.
* @param profileWriter the doclet specific writer that will output the
* result.
*
* @return an instance of a ProfileSummaryBuilder.
*/
public static ProfileSummaryBuilder getInstance(Context context,
Profile profile, ProfileSummaryWriter profileWriter) {
return new ProfileSummaryBuilder(context, profile, profileWriter);
}
/**
* Build the profile summary.
*/
public void build() throws IOException {
if (profileWriter == null) {
//Doclet does not support this output.
return;
}
build(layoutParser.parseXML(ROOT), contentTree);
}
/**
* {@inheritDoc}
*/
public String getName() {
return ROOT;
}
/**
* Build the profile documentation.
*
* @param node the XML element that specifies which components to document
* @param contentTree the content tree to which the documentation will be added
*/
public void buildProfileDoc(XMLNode node, Content contentTree) throws Exception {
contentTree = profileWriter.getProfileHeader(profile.name);
buildChildren(node, contentTree);
profileWriter.addProfileFooter(contentTree);
profileWriter.printDocument(contentTree);
profileWriter.close();
Util.copyDocFiles(configuration, DocPaths.profileSummary(profile.name));
}
/**
* Build the content for the profile doc.
*
* @param node the XML element that specifies which components to document
* @param contentTree the content tree to which the profile contents
* will be added
*/
public void buildContent(XMLNode node, Content contentTree) {
Content profileContentTree = profileWriter.getContentHeader();
buildChildren(node, profileContentTree);
contentTree.addContent(profileContentTree);
}
/**
* Build the profile summary.
*
* @param node the XML element that specifies which components to document
* @param profileContentTree the profile content tree to which the summaries will
* be added
*/
public void buildSummary(XMLNode node, Content profileContentTree) {
Content summaryContentTree = profileWriter.getSummaryHeader();
buildChildren(node, summaryContentTree);
profileContentTree.addContent(profileWriter.getSummaryTree(summaryContentTree));
}
/**
* Build the profile package summary.
*
* @param node the XML element that specifies which components to document
* @param summaryContentTree the content tree to which the summaries will
* be added
*/
public void buildPackageSummary(XMLNode node, Content summaryContentTree) {
PackageDoc[] packages = configuration.profilePackages.get(profile.name);
for (int i = 0; i < packages.length; i++) {
this.pkg = packages[i];
Content packageSummaryContentTree = profileWriter.getPackageSummaryHeader(this.pkg);
buildChildren(node, packageSummaryContentTree);
summaryContentTree.addContent(profileWriter.getPackageSummaryTree(
packageSummaryContentTree));
}
}
/**
* Build the summary for the interfaces in the package.
*
* @param node the XML element that specifies which components to document
* @param packageSummaryContentTree the tree to which the interface summary
* will be added
*/
public void buildInterfaceSummary(XMLNode node, Content packageSummaryContentTree) {
String interfaceTableSummary =
configuration.getText("doclet.Member_Table_Summary",
configuration.getText("doclet.Interface_Summary"),
configuration.getText("doclet.interfaces"));
String[] interfaceTableHeader = new String[] {
configuration.getText("doclet.Interface"),
configuration.getText("doclet.Description")
};
ClassDoc[] interfaces = pkg.interfaces();
if (interfaces.length > 0) {
profileWriter.addClassesSummary(
interfaces,
configuration.getText("doclet.Interface_Summary"),
interfaceTableSummary, interfaceTableHeader, packageSummaryContentTree);
}
}
/**
* Build the summary for the classes in the package.
*
* @param node the XML element that specifies which components to document
* @param packageSummaryContentTree the tree to which the class summary will
* be added
*/
public void buildClassSummary(XMLNode node, Content packageSummaryContentTree) {
String classTableSummary =
configuration.getText("doclet.Member_Table_Summary",
configuration.getText("doclet.Class_Summary"),
configuration.getText("doclet.classes"));
String[] classTableHeader = new String[] {
configuration.getText("doclet.Class"),
configuration.getText("doclet.Description")
};
ClassDoc[] classes = pkg.ordinaryClasses();
if (classes.length > 0) {
profileWriter.addClassesSummary(
classes,
configuration.getText("doclet.Class_Summary"),
classTableSummary, classTableHeader, packageSummaryContentTree);
}
}
/**
* Build the summary for the enums in the package.
*
* @param node the XML element that specifies which components to document
* @param packageSummaryContentTree the tree to which the enum summary will
* be added
*/
public void buildEnumSummary(XMLNode node, Content packageSummaryContentTree) {
String enumTableSummary =
configuration.getText("doclet.Member_Table_Summary",
configuration.getText("doclet.Enum_Summary"),
configuration.getText("doclet.enums"));
String[] enumTableHeader = new String[] {
configuration.getText("doclet.Enum"),
configuration.getText("doclet.Description")
};
ClassDoc[] enums = pkg.enums();
if (enums.length > 0) {
profileWriter.addClassesSummary(
enums,
configuration.getText("doclet.Enum_Summary"),
enumTableSummary, enumTableHeader, packageSummaryContentTree);
}
}
/**
* Build the summary for the exceptions in the package.
*
* @param node the XML element that specifies which components to document
* @param packageSummaryContentTree the tree to which the exception summary will
* be added
*/
public void buildExceptionSummary(XMLNode node, Content packageSummaryContentTree) {
String exceptionTableSummary =
configuration.getText("doclet.Member_Table_Summary",
configuration.getText("doclet.Exception_Summary"),
configuration.getText("doclet.exceptions"));
String[] exceptionTableHeader = new String[] {
configuration.getText("doclet.Exception"),
configuration.getText("doclet.Description")
};
ClassDoc[] exceptions = pkg.exceptions();
if (exceptions.length > 0) {
profileWriter.addClassesSummary(
exceptions,
configuration.getText("doclet.Exception_Summary"),
exceptionTableSummary, exceptionTableHeader, packageSummaryContentTree);
}
}
/**
* Build the summary for the errors in the package.
*
* @param node the XML element that specifies which components to document
* @param packageSummaryContentTree the tree to which the error summary will
* be added
*/
public void buildErrorSummary(XMLNode node, Content packageSummaryContentTree) {
String errorTableSummary =
configuration.getText("doclet.Member_Table_Summary",
configuration.getText("doclet.Error_Summary"),
configuration.getText("doclet.errors"));
String[] errorTableHeader = new String[] {
configuration.getText("doclet.Error"),
configuration.getText("doclet.Description")
};
ClassDoc[] errors = pkg.errors();
if (errors.length > 0) {
profileWriter.addClassesSummary(
errors,
configuration.getText("doclet.Error_Summary"),
errorTableSummary, errorTableHeader, packageSummaryContentTree);
}
}
/**
* Build the summary for the annotation type in the package.
*
* @param node the XML element that specifies which components to document
* @param packageSummaryContentTree the tree to which the annotation type
* summary will be added
*/
public void buildAnnotationTypeSummary(XMLNode node, Content packageSummaryContentTree) {
String annotationtypeTableSummary =
configuration.getText("doclet.Member_Table_Summary",
configuration.getText("doclet.Annotation_Types_Summary"),
configuration.getText("doclet.annotationtypes"));
String[] annotationtypeTableHeader = new String[] {
configuration.getText("doclet.AnnotationType"),
configuration.getText("doclet.Description")
};
ClassDoc[] annotationTypes = pkg.annotationTypes();
if (annotationTypes.length > 0) {
profileWriter.addClassesSummary(
annotationTypes,
configuration.getText("doclet.Annotation_Types_Summary"),
annotationtypeTableSummary, annotationtypeTableHeader,
packageSummaryContentTree);
}
}
}

228
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/PropertyBuilder.java Normal file
View File

@@ -0,0 +1,228 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.util.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.javadoc.*;
/**
* Builds documentation for a property.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.7
*/
public class PropertyBuilder extends AbstractMemberBuilder {
/**
* The class whose properties are being documented.
*/
private final ClassDoc classDoc;
/**
* The visible properties for the given class.
*/
private final VisibleMemberMap visibleMemberMap;
/**
* The writer to output the property documentation.
*/
private final PropertyWriter writer;
/**
* The list of properties being documented.
*/
private final List<ProgramElementDoc> properties;
/**
* The index of the current property that is being documented at this point
* in time.
*/
private int currentPropertyIndex;
/**
* Construct a new PropertyBuilder.
*
* @param context the build context.
* @param classDoc the class whoses members are being documented.
* @param writer the doclet specific writer.
*/
private PropertyBuilder(Context context,
ClassDoc classDoc,
PropertyWriter writer) {
super(context);
this.classDoc = classDoc;
this.writer = writer;
visibleMemberMap =
new VisibleMemberMap(
classDoc,
VisibleMemberMap.PROPERTIES,
configuration);
properties =
new ArrayList<ProgramElementDoc>(visibleMemberMap.getMembersFor(classDoc));
if (configuration.getMemberComparator() != null) {
Collections.sort(properties, configuration.getMemberComparator());
}
}
/**
* Construct a new PropertyBuilder.
*
* @param context the build context.
* @param classDoc the class whoses members are being documented.
* @param writer the doclet specific writer.
*/
public static PropertyBuilder getInstance(Context context,
ClassDoc classDoc,
PropertyWriter writer) {
return new PropertyBuilder(context, classDoc, writer);
}
/**
* {@inheritDoc}
*/
public String getName() {
return "PropertyDetails";
}
/**
* Returns a list of properties that will be documented for the given class.
* This information can be used for doclet specific documentation
* generation.
*
* @param classDoc the {@link ClassDoc} we want to check.
* @return a list of properties that will be documented.
*/
public List<ProgramElementDoc> members(ClassDoc classDoc) {
return visibleMemberMap.getMembersFor(classDoc);
}
/**
* Returns the visible member map for the properties of this class.
*
* @return the visible member map for the properties of this class.
*/
public VisibleMemberMap getVisibleMemberMap() {
return visibleMemberMap;
}
/**
* summaryOrder.size()
*/
public boolean hasMembersToDocument() {
return properties.size() > 0;
}
/**
* Build the property documentation.
*
* @param node the XML element that specifies which components to document
* @param memberDetailsTree the content tree to which the documentation will be added
*/
public void buildPropertyDoc(XMLNode node, Content memberDetailsTree) {
if (writer == null) {
return;
}
int size = properties.size();
if (size > 0) {
Content propertyDetailsTree = writer.getPropertyDetailsTreeHeader(
classDoc, memberDetailsTree);
for (currentPropertyIndex = 0; currentPropertyIndex < size;
currentPropertyIndex++) {
Content propertyDocTree = writer.getPropertyDocTreeHeader(
(MethodDoc) properties.get(currentPropertyIndex),
propertyDetailsTree);
buildChildren(node, propertyDocTree);
propertyDetailsTree.addContent(writer.getPropertyDoc(
propertyDocTree, (currentPropertyIndex == size - 1)));
}
memberDetailsTree.addContent(
writer.getPropertyDetails(propertyDetailsTree));
}
}
/**
* Build the signature.
*
* @param node the XML element that specifies which components to document
* @param propertyDocTree the content tree to which the documentation will be added
*/
public void buildSignature(XMLNode node, Content propertyDocTree) {
propertyDocTree.addContent(
writer.getSignature((MethodDoc) properties.get(currentPropertyIndex)));
}
/**
* Build the deprecation information.
*
* @param node the XML element that specifies which components to document
* @param propertyDocTree the content tree to which the documentation will be added
*/
public void buildDeprecationInfo(XMLNode node, Content propertyDocTree) {
writer.addDeprecated(
(MethodDoc) properties.get(currentPropertyIndex), propertyDocTree);
}
/**
* Build the comments for the property. Do nothing if
* {@link Configuration#nocomment} is set to true.
*
* @param node the XML element that specifies which components to document
* @param propertyDocTree the content tree to which the documentation will be added
*/
public void buildPropertyComments(XMLNode node, Content propertyDocTree) {
if (!configuration.nocomment) {
writer.addComments((MethodDoc) properties.get(currentPropertyIndex), propertyDocTree);
}
}
/**
* Build the tag information.
*
* @param node the XML element that specifies which components to document
* @param propertyDocTree the content tree to which the documentation will be added
*/
public void buildTagInfo(XMLNode node, Content propertyDocTree) {
writer.addTags((MethodDoc) properties.get(currentPropertyIndex), propertyDocTree);
}
/**
* Return the property writer for this builder.
*
* @return the property writer for this builder.
*/
public PropertyWriter getWriter() {
return writer;
}
}

595
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/SerializedFormBuilder.java Normal file
View File

@@ -0,0 +1,595 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.io.*;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
import com.sun.tools.javac.util.StringUtils;
/**
* Builds the serialized form.
*
* <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
* @author Bhavesh Patel (Modified)
* @since 1.5
*/
public class SerializedFormBuilder extends AbstractBuilder {
/**
* The root element of the serialized form XML is {@value}.
*/
public static final String NAME = "SerializedForm";
/**
* The writer for this builder.
*/
private SerializedFormWriter writer;
/**
* The writer for serializable fields.
*/
private SerializedFormWriter.SerialFieldWriter fieldWriter;
/**
* The writer for serializable method documentation.
*/
private SerializedFormWriter.SerialMethodWriter methodWriter;
/**
* The header for the serial version UID. Save the string
* here instead of the properties file because we do not want
* this string to be localized.
*/
private static final String SERIAL_VERSION_UID_HEADER = "serialVersionUID:";
/**
* The current package being documented.
*/
private PackageDoc currentPackage;
/**
* The current class being documented.
*/
private ClassDoc currentClass;
/**
* The current member being documented.
*/
protected MemberDoc currentMember;
/**
* The content that will be added to the serialized form documentation tree.
*/
private Content contentTree;
/**
* Construct a new SerializedFormBuilder.
* @param context the build context.
*/
private SerializedFormBuilder(Context context) {
super(context);
}
/**
* Construct a new SerializedFormBuilder.
* @param context the build context.
*/
public static SerializedFormBuilder getInstance(Context context) {
return new SerializedFormBuilder(context);
}
/**
* Build the serialized form.
*/
public void build() throws IOException {
if (! serialClassFoundToDocument(configuration.root.classes())) {
//Nothing to document.
return;
}
try {
writer = configuration.getWriterFactory().getSerializedFormWriter();
if (writer == null) {
//Doclet does not support this output.
return;
}
} catch (Exception e) {
throw new DocletAbortException(e);
}
build(layoutParser.parseXML(NAME), contentTree);
writer.close();
}
/**
* {@inheritDoc}
*/
public String getName() {
return NAME;
}
/**
* Build the serialized form.
*
* @param node the XML element that specifies which components to document
* @param serializedTree content tree to which the documentation will be added
*/
public void buildSerializedForm(XMLNode node, Content serializedTree) throws Exception {
serializedTree = writer.getHeader(configuration.getText(
"doclet.Serialized_Form"));
buildChildren(node, serializedTree);
writer.addFooter(serializedTree);
writer.printDocument(serializedTree);
writer.close();
}
/**
* Build the serialized form summaries.
*
* @param node the XML element that specifies which components to document
* @param serializedTree content tree to which the documentation will be added
*/
public void buildSerializedFormSummaries(XMLNode node, Content serializedTree) {
Content serializedSummariesTree = writer.getSerializedSummariesHeader();
PackageDoc[] packages = configuration.packages;
for (int i = 0; i < packages.length; i++) {
currentPackage = packages[i];
buildChildren(node, serializedSummariesTree);
}
serializedTree.addContent(writer.getSerializedContent(
serializedSummariesTree));
}
/**
* Build the package serialized form for the current package being processed.
*
* @param node the XML element that specifies which components to document
* @param serializedSummariesTree content tree to which the documentation will be added
*/
public void buildPackageSerializedForm(XMLNode node, Content serializedSummariesTree) {
Content packageSerializedTree = writer.getPackageSerializedHeader();
String foo = currentPackage.name();
ClassDoc[] classes = currentPackage.allClasses(false);
if (classes == null || classes.length == 0) {
return;
}
if (!serialInclude(currentPackage)) {
return;
}
if (!serialClassFoundToDocument(classes)) {
return;
}
buildChildren(node, packageSerializedTree);
serializedSummariesTree.addContent(packageSerializedTree);
}
/**
* Build the package header.
*
* @param node the XML element that specifies which components to document
* @param packageSerializedTree content tree to which the documentation will be added
*/
public void buildPackageHeader(XMLNode node, Content packageSerializedTree) {
packageSerializedTree.addContent(writer.getPackageHeader(
Util.getPackageName(currentPackage)));
}
/**
* Build the class serialized form.
*
* @param node the XML element that specifies which components to document
* @param packageSerializedTree content tree to which the documentation will be added
*/
public void buildClassSerializedForm(XMLNode node, Content packageSerializedTree) {
Content classSerializedTree = writer.getClassSerializedHeader();
ClassDoc[] classes = currentPackage.allClasses(false);
Arrays.sort(classes);
for (int j = 0; j < classes.length; j++) {
currentClass = classes[j];
fieldWriter = writer.getSerialFieldWriter(currentClass);
methodWriter = writer.getSerialMethodWriter(currentClass);
if(currentClass.isClass() && currentClass.isSerializable()) {
if(!serialClassInclude(currentClass)) {
continue;
}
Content classTree = writer.getClassHeader(currentClass);
buildChildren(node, classTree);
classSerializedTree.addContent(classTree);
}
}
packageSerializedTree.addContent(classSerializedTree);
}
/**
* Build the serial UID information for the given class.
*
* @param node the XML element that specifies which components to document
* @param classTree content tree to which the serial UID information will be added
*/
public void buildSerialUIDInfo(XMLNode node, Content classTree) {
Content serialUidTree = writer.getSerialUIDInfoHeader();
FieldDoc[] fields = currentClass.fields(false);
for (int i = 0; i < fields.length; i++) {
if (fields[i].name().equals("serialVersionUID") &&
fields[i].constantValueExpression() != null) {
writer.addSerialUIDInfo(SERIAL_VERSION_UID_HEADER,
fields[i].constantValueExpression(), serialUidTree);
break;
}
}
classTree.addContent(serialUidTree);
}
/**
* Build the summaries for the methods and fields.
*
* @param node the XML element that specifies which components to document
* @param classTree content tree to which the documentation will be added
*/
public void buildClassContent(XMLNode node, Content classTree) {
Content classContentTree = writer.getClassContentHeader();
buildChildren(node, classContentTree);
classTree.addContent(classContentTree);
}
/**
* Build the summaries for the methods that belong to the given
* class.
*
* @param node the XML element that specifies which components to document
* @param classContentTree content tree to which the documentation will be added
*/
public void buildSerializableMethods(XMLNode node, Content classContentTree) {
Content serializableMethodTree = methodWriter.getSerializableMethodsHeader();
MemberDoc[] members = currentClass.serializationMethods();
int membersLength = members.length;
if (membersLength > 0) {
for (int i = 0; i < membersLength; i++) {
currentMember = members[i];
Content methodsContentTree = methodWriter.getMethodsContentHeader(
(i == membersLength - 1));
buildChildren(node, methodsContentTree);
serializableMethodTree.addContent(methodsContentTree);
}
}
if (currentClass.serializationMethods().length > 0) {
classContentTree.addContent(methodWriter.getSerializableMethods(
configuration.getText("doclet.Serialized_Form_methods"),
serializableMethodTree));
if (currentClass.isSerializable() && !currentClass.isExternalizable()) {
if (currentClass.serializationMethods().length == 0) {
Content noCustomizationMsg = methodWriter.getNoCustomizationMsg(
configuration.getText(
"doclet.Serializable_no_customization"));
classContentTree.addContent(methodWriter.getSerializableMethods(
configuration.getText("doclet.Serialized_Form_methods"),
noCustomizationMsg));
}
}
}
}
/**
* Build the method sub header.
*
* @param node the XML element that specifies which components to document
* @param methodsContentTree content tree to which the documentation will be added
*/
public void buildMethodSubHeader(XMLNode node, Content methodsContentTree) {
methodWriter.addMemberHeader((MethodDoc)currentMember, methodsContentTree);
}
/**
* Build the deprecated method description.
*
* @param node the XML element that specifies which components to document
* @param methodsContentTree content tree to which the documentation will be added
*/
public void buildDeprecatedMethodInfo(XMLNode node, Content methodsContentTree) {
methodWriter.addDeprecatedMemberInfo((MethodDoc) currentMember, methodsContentTree);
}
/**
* Build the information for the method.
*
* @param node the XML element that specifies which components to document
* @param methodsContentTree content tree to which the documentation will be added
*/
public void buildMethodInfo(XMLNode node, Content methodsContentTree) {
if(configuration.nocomment){
return;
}
buildChildren(node, methodsContentTree);
}
/**
* Build method description.
*
* @param node the XML element that specifies which components to document
* @param methodsContentTree content tree to which the documentation will be added
*/
public void buildMethodDescription(XMLNode node, Content methodsContentTree) {
methodWriter.addMemberDescription((MethodDoc) currentMember, methodsContentTree);
}
/**
* Build the method tags.
*
* @param node the XML element that specifies which components to document
* @param methodsContentTree content tree to which the documentation will be added
*/
public void buildMethodTags(XMLNode node, Content methodsContentTree) {
methodWriter.addMemberTags((MethodDoc) currentMember, methodsContentTree);
MethodDoc method = (MethodDoc)currentMember;
if (method.name().compareTo("writeExternal") == 0
&& method.tags("serialData").length == 0) {
if (configuration.serialwarn) {
configuration.getDocletSpecificMsg().warning(
currentMember.position(), "doclet.MissingSerialDataTag",
method.containingClass().qualifiedName(), method.name());
}
}
}
/**
* Build the field header.
*
* @param node the XML element that specifies which components to document
* @param classContentTree content tree to which the documentation will be added
*/
public void buildFieldHeader(XMLNode node, Content classContentTree) {
if (currentClass.serializableFields().length > 0) {
buildFieldSerializationOverview(currentClass, classContentTree);
}
}
/**
* Build the serialization overview for the given class.
*
* @param classDoc the class to print the overview for.
* @param classContentTree content tree to which the documentation will be added
*/
public void buildFieldSerializationOverview(ClassDoc classDoc, Content classContentTree) {
if (classDoc.definesSerializableFields()) {
FieldDoc serialPersistentField = classDoc.serializableFields()[0];
// Check to see if there are inline comments, tags or deprecation
// information to be printed.
if (fieldWriter.shouldPrintOverview(serialPersistentField)) {
Content serializableFieldsTree = fieldWriter.getSerializableFieldsHeader();
Content fieldsOverviewContentTree = fieldWriter.getFieldsContentHeader(true);
fieldWriter.addMemberDeprecatedInfo(serialPersistentField,
fieldsOverviewContentTree);
if (!configuration.nocomment) {
fieldWriter.addMemberDescription(serialPersistentField,
fieldsOverviewContentTree);
fieldWriter.addMemberTags(serialPersistentField,
fieldsOverviewContentTree);
}
serializableFieldsTree.addContent(fieldsOverviewContentTree);
classContentTree.addContent(fieldWriter.getSerializableFields(
configuration.getText("doclet.Serialized_Form_class"),
serializableFieldsTree));
}
}
}
/**
* Build the summaries for the fields that belong to the given class.
*
* @param node the XML element that specifies which components to document
* @param classContentTree content tree to which the documentation will be added
*/
public void buildSerializableFields(XMLNode node, Content classContentTree) {
MemberDoc[] members = currentClass.serializableFields();
int membersLength = members.length;
if (membersLength > 0) {
Content serializableFieldsTree = fieldWriter.getSerializableFieldsHeader();
for (int i = 0; i < membersLength; i++) {
currentMember = members[i];
if (!currentClass.definesSerializableFields()) {
Content fieldsContentTree = fieldWriter.getFieldsContentHeader(
(i == membersLength - 1));
buildChildren(node, fieldsContentTree);
serializableFieldsTree.addContent(fieldsContentTree);
}
else {
buildSerialFieldTagsInfo(serializableFieldsTree);
}
}
classContentTree.addContent(fieldWriter.getSerializableFields(
configuration.getText("doclet.Serialized_Form_fields"),
serializableFieldsTree));
}
}
/**
* Build the field sub header.
*
* @param node the XML element that specifies which components to document
* @param fieldsContentTree content tree to which the documentation will be added
*/
public void buildFieldSubHeader(XMLNode node, Content fieldsContentTree) {
if (!currentClass.definesSerializableFields()) {
FieldDoc field = (FieldDoc) currentMember;
fieldWriter.addMemberHeader(field.type().asClassDoc(),
field.type().typeName(), field.type().dimension(), field.name(),
fieldsContentTree);
}
}
/**
* Build the field deprecation information.
*
* @param node the XML element that specifies which components to document
* @param fieldsContentTree content tree to which the documentation will be added
*/
public void buildFieldDeprecationInfo(XMLNode node, Content fieldsContentTree) {
if (!currentClass.definesSerializableFields()) {
FieldDoc field = (FieldDoc)currentMember;
fieldWriter.addMemberDeprecatedInfo(field, fieldsContentTree);
}
}
/**
* Build the serial field tags information.
*
* @param serializableFieldsTree content tree to which the documentation will be added
*/
public void buildSerialFieldTagsInfo(Content serializableFieldsTree) {
if(configuration.nocomment){
return;
}
FieldDoc field = (FieldDoc)currentMember;
// Process Serializable Fields specified as array of
// ObjectStreamFields. Print a member for each serialField tag.
// (There should be one serialField tag per ObjectStreamField
// element.)
SerialFieldTag[] tags = field.serialFieldTags();
Arrays.sort(tags);
int tagsLength = tags.length;
for (int i = 0; i < tagsLength; i++) {
if (tags[i].fieldName() == null || tags[i].fieldType() == null) // ignore malformed @serialField tags
continue;
Content fieldsContentTree = fieldWriter.getFieldsContentHeader(
(i == tagsLength - 1));
fieldWriter.addMemberHeader(tags[i].fieldTypeDoc(),
tags[i].fieldType(), "", tags[i].fieldName(), fieldsContentTree);
fieldWriter.addMemberDescription(tags[i], fieldsContentTree);
serializableFieldsTree.addContent(fieldsContentTree);
}
}
/**
* Build the field information.
*
* @param node the XML element that specifies which components to document
* @param fieldsContentTree content tree to which the documentation will be added
*/
public void buildFieldInfo(XMLNode node, Content fieldsContentTree) {
if(configuration.nocomment){
return;
}
FieldDoc field = (FieldDoc)currentMember;
ClassDoc cd = field.containingClass();
// Process default Serializable field.
if ((field.tags("serial").length == 0) && ! field.isSynthetic()
&& configuration.serialwarn) {
configuration.message.warning(field.position(),
"doclet.MissingSerialTag", cd.qualifiedName(),
field.name());
}
fieldWriter.addMemberDescription(field, fieldsContentTree);
fieldWriter.addMemberTags(field, fieldsContentTree);
}
/**
* Return true if the given Doc should be included
* in the serialized form.
*
* @param doc the Doc object to check for serializability.
*/
public static boolean serialInclude(Doc doc) {
if (doc == null) {
return false;
}
return doc.isClass() ?
serialClassInclude((ClassDoc)doc) :
serialDocInclude(doc);
}
/**
* Return true if the given ClassDoc should be included
* in the serialized form.
*
* @param cd the ClassDoc object to check for serializability.
*/
private static boolean serialClassInclude(ClassDoc cd) {
if (cd.isEnum()) {
return false;
}
try {
cd.superclassType();
} catch (NullPointerException e) {
//Workaround for null pointer bug in ClassDoc.superclassType().
return false;
}
if (cd.isSerializable()) {
if (cd.tags("serial").length > 0) {
return serialDocInclude(cd);
} else if (cd.isPublic() || cd.isProtected()) {
return true;
} else {
return false;
}
}
return false;
}
/**
* Return true if the given Doc should be included
* in the serialized form.
*
* @param doc the Doc object to check for serializability.
*/
private static boolean serialDocInclude(Doc doc) {
if (doc.isEnum()) {
return false;
}
Tag[] serial = doc.tags("serial");
if (serial.length > 0) {
String serialtext = StringUtils.toLowerCase(serial[0].text());
if (serialtext.indexOf("exclude") >= 0) {
return false;
} else if (serialtext.indexOf("include") >= 0) {
return true;
}
}
return true;
}
/**
* Return true if any of the given classes have a @serialinclude tag.
*
* @param classes the classes to check.
* @return true if any of the given classes have a @serialinclude tag.
*/
private boolean serialClassFoundToDocument(ClassDoc[] classes) {
for (int i = 0; i < classes.length; i++) {
if (serialClassInclude(classes[i])) {
return true;
}
}
return false;
}
}

74
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/XMLNode.java Normal file
View File

@@ -0,0 +1,74 @@
/*
* Copyright (c) 2010, 2012, 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 com.sun.tools.doclets.internal.toolkit.builders;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
/**
* Simple class to represent the attribute and elements of an XML node.
*
* <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 XMLNode {
XMLNode(XMLNode parent, String qname) {
this.parent = parent;
name = qname;
attrs = new HashMap<String,String>();
children = new ArrayList<XMLNode>();
if (parent != null)
parent.children.add(this);
}
@Override
public String toString() {
StringBuilder sb = new StringBuilder();
sb.append("<");
sb.append(name);
for (Map.Entry<String,String> e: attrs.entrySet())
sb.append(" " + e.getKey() + "=\"" + e.getValue() + "\"");
if (children.size() == 0)
sb.append("/>");
else {
sb.append(">");
for (XMLNode c: children)
sb.append(c.toString());
sb.append("</" + name + ">");
}
return sb.toString();
}
final XMLNode parent;
final String name;
final Map<String,String> attrs;
final List<XMLNode> children;
}

41
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/builders/package-info.java Normal file
View File

@@ -0,0 +1,41 @@
/*
* Copyright (c) 2003, 2013, 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.
*/
/**
This doclet-independent package has a set of classes and
interfaces that are the building blocks for doclets. They
define the basic structure of doclets and make doclet
writing much easier because they provide the content generation
code to be shared among different doclets. Builders only provide
the structure and content of API documentation.
They will not provide any style markup.
<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>
*/
@jdk.Exported(false)
package com.sun.tools.doclets.internal.toolkit.builders;

57
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/package-info.java Normal file
View File

@@ -0,0 +1,57 @@
/*
* Copyright (c) 2003, 2013, 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.
*/
/**
Contains the base classes that make up a doclet. Doclets that reuse
the functionality provided by the toolkit should have the following
characteristics:
<ul>
<li>
The main driver class should extend
{@link com.sun.tools.doclets.internal.toolkit.AbstractDoclet}.
</li>
<li>
The doclet configuration class should extend
{@link com.sun.tools.doclets.internal.toolkit.Configuration}.
</li>
<li>
The doclet should have a writer factory that implements
{@link com.sun.tools.doclets.internal.toolkit.WriterFactory}.
This class constructs writers that write doclet specific output.
</li>
<li>
The doclet should have a taglet writer that extends
{@link com.sun.tools.doclets.internal.toolkit.taglets.TagletWriter}.
This writer determines how to output each given tag.
</li>
</ul>
<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>
*/
@jdk.Exported(false)
package com.sun.tools.doclets.internal.toolkit;

196
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/resources/doclets.java Normal file
View File

@@ -0,0 +1,196 @@
package com.sun.tools.doclets.internal.toolkit.resources;
public final class doclets extends java.util.ListResourceBundle {
protected final Object[][] getContents() {
return new Object[][] {
{ "doclet.0_and_1", "{0} and {1}" },
{ "doclet.Abstract_Methods", "Abstract Methods" },
{ "doclet.All_Classes", "All Classes" },
{ "doclet.All_Implemented_Interfaces", "All Implemented Interfaces:" },
{ "doclet.All_Methods", "All Methods" },
{ "doclet.All_Superinterfaces", "All Superinterfaces:" },
{ "doclet.All_classes_and_interfaces", "All classes and interfaces (except non-static nested types)" },
{ "doclet.AnnotationType", "Annotation Type" },
{ "doclet.AnnotationTypes", "Annotation Types" },
{ "doclet.Annotation_Type_Member", "Annotation Type Element" },
{ "doclet.Annotation_Type_Member_Detail", "Element Detail" },
{ "doclet.Annotation_Type_Optional_Member", "Optional Element" },
{ "doclet.Annotation_Type_Optional_Member_Summary", "Optional Element Summary" },
{ "doclet.Annotation_Type_Optional_Members", "Optional Elements" },
{ "doclet.Annotation_Type_Required_Member", "Required Element" },
{ "doclet.Annotation_Type_Required_Member_Summary", "Required Element Summary" },
{ "doclet.Annotation_Type_Required_Members", "Required Elements" },
{ "doclet.Annotation_Types_Summary", "Annotation Types Summary" },
{ "doclet.Author", "Author:" },
{ "doclet.Building_Index", "Building index for all the packages and classes..." },
{ "doclet.Building_Index_For_All_Classes", "Building index for all classes..." },
{ "doclet.Building_Tree", "Building tree for all the packages and classes..." },
{ "doclet.Class", "Class" },
{ "doclet.Class_0_extends_implements_serializable", "Class {0} extends {1} implements Serializable" },
{ "doclet.Class_0_implements_serializable", "Class {0} implements Serializable" },
{ "doclet.Class_Summary", "Class Summary" },
{ "doclet.Classes", "Classes" },
{ "doclet.Concrete_Methods", "Concrete Methods" },
{ "doclet.ConstantField", "Constant Field" },
{ "doclet.Constants_Summary", "Constant Field Values" },
{ "doclet.Constants_Table_Summary", "{0} table, listing constant fields, and values" },
{ "doclet.Constructor", "Constructor" },
{ "doclet.Constructor_Detail", "Constructor Detail" },
{ "doclet.Constructor_Summary", "Constructor Summary" },
{ "doclet.Constructors", "Constructors" },
{ "doclet.Copy_Overwrite_warning", "File {0} not copied to {1} due to existing file with same name..." },
{ "doclet.Copying_File_0_To_Dir_1", "Copying file {0} to directory {1}..." },
{ "doclet.Copying_File_0_To_File_1", "Copying file {0} to file {1}..." },
{ "doclet.Default", "Default:" },
{ "doclet.DefaultValue", "Default value:" },
{ "doclet.Default_Methods", "Default Methods" },
{ "doclet.Deprecated", "Deprecated." },
{ "doclet.Deprecated_Methods", "Deprecated Methods" },
{ "doclet.Description", "Description" },
{ "doclet.Encoding_not_supported", "Encoding not supported: {0}" },
{ "doclet.Enum", "Enum" },
{ "doclet.Enum_Constant", "Enum Constant" },
{ "doclet.Enum_Constant_Detail", "Enum Constant Detail" },
{ "doclet.Enum_Constant_Summary", "Enum Constant Summary" },
{ "doclet.Enum_Constants", "Enum Constants" },
{ "doclet.Enum_Summary", "Enum Summary" },
{ "doclet.Enums", "Enums" },
{ "doclet.Error", "Error" },
{ "doclet.Error_Summary", "Error Summary" },
{ "doclet.Error_invalid_custom_tag_argument", "Error - {0} is an invalid argument to the -tag option..." },
{ "doclet.Error_taglet_not_registered", "Error - Exception {0} thrown while trying to register Taglet {1}..." },
{ "doclet.Errors", "Errors" },
{ "doclet.Exception", "Exception" },
{ "doclet.Exception_Summary", "Exception Summary" },
{ "doclet.Exceptions", "Exceptions" },
{ "doclet.Factory", "Factory:" },
{ "doclet.Field", "Field" },
{ "doclet.Field_Detail", "Field Detail" },
{ "doclet.Field_Summary", "Field Summary" },
{ "doclet.Fields", "Fields" },
{ "doclet.Fields_Inherited_From_Class", "Fields inherited from class" },
{ "doclet.Fields_Inherited_From_Interface", "Fields inherited from interface" },
{ "doclet.File_not_found", "File not found: {0}" },
{ "doclet.Generating_0", "Generating {0}..." },
{ "doclet.Groupname_already_used", "In -group option, groupname already used: {0}" },
{ "doclet.Instance_Methods", "Instance Methods" },
{ "doclet.Interface", "Interface" },
{ "doclet.Interface_Summary", "Interface Summary" },
{ "doclet.Interfaces", "Interfaces" },
{ "doclet.JavaScript_in_option", "Argument for {0} contains JavaScript.\nUse --allow-script-in-comments to allow use of JavaScript." },
{ "doclet.Member_Table_Summary", "{0} table, listing {1}, and an explanation" },
{ "doclet.Method", "Method" },
{ "doclet.Method_Detail", "Method Detail" },
{ "doclet.Method_Summary", "Method Summary" },
{ "doclet.Methods", "Methods" },
{ "doclet.Methods_Inherited_From_Class", "Methods inherited from class" },
{ "doclet.Methods_Inherited_From_Interface", "Methods inherited from interface" },
{ "doclet.MissingSerialDataTag", "in class {0}, missing @serialData tag in method {1}." },
{ "doclet.MissingSerialTag", "in class {0}, missing @serial tag for default serializable field: {1}." },
{ "doclet.Modifier", "Modifier" },
{ "doclet.Nested_Class_Summary", "Nested Class Summary" },
{ "doclet.Nested_Classes", "Nested Classes" },
{ "doclet.Nested_Classes_Interface_Inherited_From_Interface", "Nested classes/interfaces inherited from interface" },
{ "doclet.Nested_Classes_Interfaces_Inherited_From_Class", "Nested classes/interfaces inherited from class" },
{ "doclet.No_Public_Classes_To_Document", "No public or protected classes found to document." },
{ "doclet.Notice_taglet_conflict_warn", "Note: Custom tags that could override future standard tags: {0}. To avoid potential overrides, use at least one period character (.) in custom tag names." },
{ "doclet.Notice_taglet_overriden", "Note: Custom tags that override standard tags: {0}" },
{ "doclet.Notice_taglet_registered", "Registered Taglet {0} ..." },
{ "doclet.Notice_taglet_unseen", "Note: Custom tags that were not seen: {0}" },
{ "doclet.Option_conflict", "Option {0} conflicts with {1}" },
{ "doclet.Option_doclint_invalid_arg", "Invalid argument for -Xdoclint option" },
{ "doclet.Option_doclint_no_qualifiers", "Access qualifiers not permitted for -Xdoclint arguments" },
{ "doclet.Option_reuse", "Option reused: {0}" },
{ "doclet.Other_Packages", "Other Packages" },
{ "doclet.Package_Summary", "Package Summary" },
{ "doclet.Package_class_and_interface_descriptions", "Package, class and interface descriptions" },
{ "doclet.Package_private", "(package private)" },
{ "doclet.Packages", "Packages" },
{ "doclet.Parameters", "Parameters:" },
{ "doclet.Parameters_dup_warn", "Parameter \"{0}\" is documented more than once." },
{ "doclet.Parameters_warn", "@param argument \"{0}\" is not a parameter name." },
{ "doclet.Profile_Summary", "Profile Summary" },
{ "doclet.Profiles", "Profiles" },
{ "doclet.Properties", "Properties" },
{ "doclet.Properties_Inherited_From_Class", "Properties inherited from class" },
{ "doclet.Properties_Inherited_From_Interface", "Properties inherited from interface" },
{ "doclet.Property", "Property" },
{ "doclet.PropertyDescription", "Property description:" },
{ "doclet.PropertyGetter", "Gets the value of the property" },
{ "doclet.PropertyGetterWithName", "Gets the value of the property {0}." },
{ "doclet.PropertySetter", "Sets the value of the property" },
{ "doclet.PropertySetterWithName", "Sets the value of the property {0}." },
{ "doclet.Property_Detail", "Property Detail" },
{ "doclet.Property_Summary", "Property Summary" },
{ "doclet.Return_tag_on_void_method", "@return tag cannot be used in method with void return type." },
{ "doclet.Returns", "Returns:" },
{ "doclet.See", "See:" },
{ "doclet.See_Also", "See Also:" },
{ "doclet.SerialData", "Serial Data:" },
{ "doclet.Serializable_no_customization", "No readObject or writeObject method declared." },
{ "doclet.Serialized_Form", "Serialized Form" },
{ "doclet.Serialized_Form_class", "Serialization Overview" },
{ "doclet.Serialized_Form_fields", "Serialized Fields" },
{ "doclet.Serialized_Form_methods", "Serialization Methods" },
{ "doclet.Since", "Since:" },
{ "doclet.Static_Methods", "Static Methods" },
{ "doclet.Throws", "Throws:" },
{ "doclet.Toolkit_Usage_Violation", "The Doclet Toolkit can only be used by {0}" },
{ "doclet.Type", "Type" },
{ "doclet.TypeParameters", "Type Parameters:" },
{ "doclet.Type_Parameters_dup_warn", "Type parameter \"{0}\" is documented more than once." },
{ "doclet.Type_Parameters_warn", "@param argument \"{0}\" is not a type parameter name." },
{ "doclet.Unable_to_create_directory_0", "Unable to create directory {0}" },
{ "doclet.UnknownTag", "{0} is an unknown tag." },
{ "doclet.UnknownTagLowercase", "{0} is an unknown tag -- same as a known tag except for case." },
{ "doclet.Use_Table_Summary", "Use table, listing {0}, and an explanation" },
{ "doclet.Value", "Value" },
{ "doclet.Version", "Version:" },
{ "doclet.annotation_type_optional_members", "optional elements" },
{ "doclet.annotation_type_required_members", "required elements" },
{ "doclet.annotationtype", "annotation type" },
{ "doclet.annotationtypes", "annotation types" },
{ "doclet.class", "class" },
{ "doclet.classes", "classes" },
{ "doclet.constructors", "constructors" },
{ "doclet.dest_dir_create", "Creating destination directory: \"{0}\"" },
{ "doclet.destination_directory_not_directory_0", "Destination directory is not a directory {0}" },
{ "doclet.destination_directory_not_writable_0", "Destination directory not writable {0}" },
{ "doclet.enum", "enum" },
{ "doclet.enum_constants", "enum constants" },
{ "doclet.enum_valueof_doc.main", "\nReturns the enum constant of this type with the specified name.\nThe string must match <i>exactly</i> an identifier used to declare an\nenum constant in this type. (Extraneous whitespace characters are \nnot permitted.)" },
{ "doclet.enum_valueof_doc.param_name", "the name of the enum constant to be returned." },
{ "doclet.enum_valueof_doc.return", "the enum constant with the specified name" },
{ "doclet.enum_valueof_doc.throws_ila", "if this enum type has no constant with the specified name" },
{ "doclet.enum_valueof_doc.throws_npe", "if the argument is null" },
{ "doclet.enum_values_doc.main", "\nReturns an array containing the constants of this enum type, in\nthe order they are declared. This method may be used to iterate\nover the constants as follows:\n<pre>\nfor ({0} c : {0}.values())\n&nbsp; System.out.println(c);\n</pre>" },
{ "doclet.enum_values_doc.return", "\nan array containing the constants of this enum type, in the order they are declared" },
{ "doclet.enums", "enums" },
{ "doclet.error", "error" },
{ "doclet.errors", "errors" },
{ "doclet.exception", "exception" },
{ "doclet.exception_encountered", "{0} encountered \n\twhile attempting to create file: {1}" },
{ "doclet.exceptions", "exceptions" },
{ "doclet.fields", "fields" },
{ "doclet.in", "{0} in {1}" },
{ "doclet.interface", "interface" },
{ "doclet.interfaces", "interfaces" },
{ "doclet.javafx_tag_misuse", "Tags @propertyGetter, @propertySetter and @propertyDescription can only be used in JavaFX properties getters and setters." },
{ "doclet.malformed_html_link_tag", "<a> tag is malformed:\n\"{0}\"" },
{ "doclet.methods", "methods" },
{ "doclet.nested_classes", "nested classes" },
{ "doclet.noInheritedDoc", "@inheritDoc used but {0} does not override or implement any method." },
{ "doclet.packages", "packages" },
{ "doclet.perform_copy_exception_encountered", "{0} encountered while \nperforming copy." },
{ "doclet.profiles", "profiles" },
{ "doclet.properties", "properties" },
{ "doclet.sourcetab_warning", "The argument for -sourcetab must be an integer greater than 0." },
{ "doclet.subclasses", "subclasses" },
{ "doclet.subinterfaces", "subinterfaces" },
{ "doclet.tag_misuse", "Tag {0} cannot be used in {1} documentation. It can only be used in the following types of documentation: {2}." },
{ "doclet.value_tag_invalid_constant", "@value tag (which references {0}) can only be used in constants." },
{ "doclet.value_tag_invalid_reference", "{0} (referenced by @value tag) is an unknown reference." },
{ "doclet.value_tag_invalid_use", "@value tag cannot be used here." },
};
}
}

196
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/resources/doclets_ja.java Normal file
View File

@@ -0,0 +1,196 @@
package com.sun.tools.doclets.internal.toolkit.resources;
public final class doclets_ja extends java.util.ListResourceBundle {
protected final Object[][] getContents() {
return new Object[][] {
{ "doclet.0_and_1", "{0}\u3068{1}" },
{ "doclet.Abstract_Methods", "abstract\u30E1\u30BD\u30C3\u30C9" },
{ "doclet.All_Classes", "\u3059\u3079\u3066\u306E\u30AF\u30E9\u30B9" },
{ "doclet.All_Implemented_Interfaces", "\u3059\u3079\u3066\u306E\u5B9F\u88C5\u3055\u308C\u305F\u30A4\u30F3\u30BF\u30D5\u30A7\u30FC\u30B9:" },
{ "doclet.All_Methods", "\u3059\u3079\u3066\u306E\u30E1\u30BD\u30C3\u30C9" },
{ "doclet.All_Superinterfaces", "\u3059\u3079\u3066\u306E\u30B9\u30FC\u30D1\u30FC\u30A4\u30F3\u30BF\u30D5\u30A7\u30FC\u30B9:" },
{ "doclet.All_classes_and_interfaces", "\u3059\u3079\u3066\u306E\u30AF\u30E9\u30B9\u304A\u3088\u3073\u30A4\u30F3\u30BF\u30D5\u30A7\u30FC\u30B9(\u975Estatic\u306E\u30CD\u30B9\u30C8\u3055\u308C\u305F\u578B\u3092\u9664\u304F)" },
{ "doclet.AnnotationType", "\u6CE8\u91C8\u578B" },
{ "doclet.AnnotationTypes", "\u6CE8\u91C8\u578B" },
{ "doclet.Annotation_Type_Member", "\u6CE8\u91C8\u578B\u8981\u7D20" },
{ "doclet.Annotation_Type_Member_Detail", "\u8981\u7D20\u306E\u8A73\u7D30" },
{ "doclet.Annotation_Type_Optional_Member", "\u4EFB\u610F\u8981\u7D20" },
{ "doclet.Annotation_Type_Optional_Member_Summary", "\u4EFB\u610F\u8981\u7D20\u306E\u30B5\u30DE\u30EA\u30FC" },
{ "doclet.Annotation_Type_Optional_Members", "\u4EFB\u610F\u8981\u7D20" },
{ "doclet.Annotation_Type_Required_Member", "\u5FC5\u9808\u8981\u7D20" },
{ "doclet.Annotation_Type_Required_Member_Summary", "\u5FC5\u9808\u8981\u7D20\u306E\u30B5\u30DE\u30EA\u30FC" },
{ "doclet.Annotation_Type_Required_Members", "\u5FC5\u9808\u8981\u7D20" },
{ "doclet.Annotation_Types_Summary", "\u6CE8\u91C8\u578B\u306E\u30B5\u30DE\u30EA\u30FC" },
{ "doclet.Author", "\u4F5C\u6210\u8005:" },
{ "doclet.Building_Index", "\u5168\u30D1\u30C3\u30B1\u30FC\u30B8\u3068\u30AF\u30E9\u30B9\u306E\u30A4\u30F3\u30C7\u30C3\u30AF\u30B9\u3092\u4F5C\u6210\u3057\u3066\u3044\u307E\u3059..." },
{ "doclet.Building_Index_For_All_Classes", "\u5168\u30AF\u30E9\u30B9\u306E\u30A4\u30F3\u30C7\u30C3\u30AF\u30B9\u3092\u4F5C\u6210\u3057\u3066\u3044\u307E\u3059..." },
{ "doclet.Building_Tree", "\u5168\u30D1\u30C3\u30B1\u30FC\u30B8\u3068\u30AF\u30E9\u30B9\u306E\u968E\u5C64\u30C4\u30EA\u30FC\u3092\u4F5C\u6210\u3057\u3066\u3044\u307E\u3059..." },
{ "doclet.Class", "\u30AF\u30E9\u30B9" },
{ "doclet.Class_0_extends_implements_serializable", "Class {0} extends {1} implements Serializable" },
{ "doclet.Class_0_implements_serializable", "Class {0} implements Serializable" },
{ "doclet.Class_Summary", "\u30AF\u30E9\u30B9\u306E\u30B5\u30DE\u30EA\u30FC" },
{ "doclet.Classes", "\u30AF\u30E9\u30B9" },
{ "doclet.Concrete_Methods", "concrete\u30E1\u30BD\u30C3\u30C9" },
{ "doclet.ConstantField", "\u5B9A\u6570\u30D5\u30A3\u30FC\u30EB\u30C9" },
{ "doclet.Constants_Summary", "\u5B9A\u6570\u30D5\u30A3\u30FC\u30EB\u30C9\u5024" },
{ "doclet.Constants_Table_Summary", "{0}\u8868\u3001\u5B9A\u6570\u30D5\u30A3\u30FC\u30EB\u30C9\u306E\u30EA\u30B9\u30C8\u304A\u3088\u3073\u5024" },
{ "doclet.Constructor", "\u30B3\u30F3\u30B9\u30C8\u30E9\u30AF\u30BF" },
{ "doclet.Constructor_Detail", "\u30B3\u30F3\u30B9\u30C8\u30E9\u30AF\u30BF\u306E\u8A73\u7D30" },
{ "doclet.Constructor_Summary", "\u30B3\u30F3\u30B9\u30C8\u30E9\u30AF\u30BF\u306E\u30B5\u30DE\u30EA\u30FC" },
{ "doclet.Constructors", "\u30B3\u30F3\u30B9\u30C8\u30E9\u30AF\u30BF" },
{ "doclet.Copy_Overwrite_warning", "\u30D5\u30A1\u30A4\u30EB{0}\u306F\u540C\u3058\u540D\u524D\u306E\u30D5\u30A1\u30A4\u30EB\u304C\u3042\u308B\u306E\u3067{1}\u306B\u30B3\u30D4\u30FC\u3055\u308C\u307E\u305B\u3093\u3067\u3057\u305F..." },
{ "doclet.Copying_File_0_To_Dir_1", "\u30D5\u30A1\u30A4\u30EB{0}\u3092\u30C7\u30A3\u30EC\u30AF\u30C8\u30EA{1}\u306B\u30B3\u30D4\u30FC\u4E2D..." },
{ "doclet.Copying_File_0_To_File_1", "\u30D5\u30A1\u30A4\u30EB{0}\u3092\u30D5\u30A1\u30A4\u30EB{1}\u306B\u30B3\u30D4\u30FC\u4E2D..." },
{ "doclet.Default", "\u30C7\u30D5\u30A9\u30EB\u30C8:" },
{ "doclet.DefaultValue", "\u30C7\u30D5\u30A9\u30EB\u30C8\u5024:" },
{ "doclet.Default_Methods", "\u30C7\u30D5\u30A9\u30EB\u30C8\u30FB\u30E1\u30BD\u30C3\u30C9" },
{ "doclet.Deprecated", "\u975E\u63A8\u5968\u3067\u3059\u3002" },
{ "doclet.Deprecated_Methods", "\u63A8\u5968\u3055\u308C\u3066\u3044\u306A\u3044\u30E1\u30BD\u30C3\u30C9" },
{ "doclet.Description", "\u8AAC\u660E" },
{ "doclet.Encoding_not_supported", "\u30A8\u30F3\u30B3\u30FC\u30C7\u30A3\u30F3\u30B0{0}\u306F\u30B5\u30DD\u30FC\u30C8\u3055\u308C\u3066\u3044\u307E\u305B\u3093" },
{ "doclet.Enum", "\u5217\u6319" },
{ "doclet.Enum_Constant", "\u5217\u6319\u578B\u5B9A\u6570" },
{ "doclet.Enum_Constant_Detail", "\u5217\u6319\u578B\u5B9A\u6570\u306E\u8A73\u7D30" },
{ "doclet.Enum_Constant_Summary", "\u5217\u6319\u578B\u5B9A\u6570\u306E\u30B5\u30DE\u30EA\u30FC" },
{ "doclet.Enum_Constants", "\u5217\u6319\u578B\u5B9A\u6570" },
{ "doclet.Enum_Summary", "\u5217\u6319\u578B\u306E\u30B5\u30DE\u30EA\u30FC" },
{ "doclet.Enums", "\u5217\u6319" },
{ "doclet.Error", "\u30A8\u30E9\u30FC" },
{ "doclet.Error_Summary", "\u30A8\u30E9\u30FC\u306E\u30B5\u30DE\u30EA\u30FC" },
{ "doclet.Error_invalid_custom_tag_argument", "\u30A8\u30E9\u30FC - {0}\u306F-tag\u30AA\u30D7\u30B7\u30E7\u30F3\u306B\u5BFE\u3057\u3066\u7121\u52B9\u306A\u5F15\u6570\u3067\u3059..." },
{ "doclet.Error_taglet_not_registered", "\u30A8\u30E9\u30FC - \u30BF\u30B0\u30EC\u30C3\u30C8{1}\u3092\u767B\u9332\u3057\u3088\u3046\u3068\u3057\u3066\u3044\u308B\u3068\u304D\u306B\u3001\u4F8B\u5916{0}\u304C\u30B9\u30ED\u30FC\u3055\u308C\u307E\u3057\u305F..." },
{ "doclet.Errors", "\u30A8\u30E9\u30FC" },
{ "doclet.Exception", "\u4F8B\u5916" },
{ "doclet.Exception_Summary", "\u4F8B\u5916\u306E\u30B5\u30DE\u30EA\u30FC" },
{ "doclet.Exceptions", "\u4F8B\u5916" },
{ "doclet.Factory", "\u30D5\u30A1\u30AF\u30C8\u30EA:" },
{ "doclet.Field", "\u30D5\u30A3\u30FC\u30EB\u30C9" },
{ "doclet.Field_Detail", "\u30D5\u30A3\u30FC\u30EB\u30C9\u306E\u8A73\u7D30" },
{ "doclet.Field_Summary", "\u30D5\u30A3\u30FC\u30EB\u30C9\u306E\u30B5\u30DE\u30EA\u30FC" },
{ "doclet.Fields", "\u30D5\u30A3\u30FC\u30EB\u30C9" },
{ "doclet.Fields_Inherited_From_Class", "\u30AF\u30E9\u30B9\u304B\u3089\u7D99\u627F\u3055\u308C\u305F\u30D5\u30A3\u30FC\u30EB\u30C9" },
{ "doclet.Fields_Inherited_From_Interface", "\u30A4\u30F3\u30BF\u30D5\u30A7\u30FC\u30B9\u304B\u3089\u7D99\u627F\u3055\u308C\u305F\u30D5\u30A3\u30FC\u30EB\u30C9" },
{ "doclet.File_not_found", "\u30D5\u30A1\u30A4\u30EB\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093: {0}" },
{ "doclet.Generating_0", "{0}\u306E\u751F\u6210\u4E2D..." },
{ "doclet.Groupname_already_used", "-group\u30AA\u30D7\u30B7\u30E7\u30F3\u306B\u304A\u3044\u3066\u3001\u3059\u3067\u306B\u30B0\u30EB\u30FC\u30D7\u540D\u304C\u4F7F\u7528\u3055\u308C\u3066\u3044\u307E\u3059: {0}" },
{ "doclet.Instance_Methods", "\u30A4\u30F3\u30B9\u30BF\u30F3\u30B9\u30FB\u30E1\u30BD\u30C3\u30C9" },
{ "doclet.Interface", "\u30A4\u30F3\u30BF\u30D5\u30A7\u30FC\u30B9" },
{ "doclet.Interface_Summary", "\u30A4\u30F3\u30BF\u30D5\u30A7\u30FC\u30B9\u306E\u30B5\u30DE\u30EA\u30FC" },
{ "doclet.Interfaces", "\u30A4\u30F3\u30BF\u30D5\u30A7\u30FC\u30B9" },
{ "doclet.JavaScript_in_option", "{0}\u306E\u5F15\u6570\u306BJavaScript\u304C\u542B\u307E\u308C\u3066\u3044\u307E\u3059\u3002\n--allow-script-in-comments\u3092\u4F7F\u7528\u3057\u3066\u3001JavaScript\u306E\u4F7F\u7528\u3092\u8A31\u53EF\u3057\u3066\u304F\u3060\u3055\u3044\u3002" },
{ "doclet.Member_Table_Summary", "{0}\u8868\u3001{1}\u306E\u30EA\u30B9\u30C8\u304A\u3088\u3073\u8AAC\u660E" },
{ "doclet.Method", "\u30E1\u30BD\u30C3\u30C9" },
{ "doclet.Method_Detail", "\u30E1\u30BD\u30C3\u30C9\u306E\u8A73\u7D30" },
{ "doclet.Method_Summary", "\u30E1\u30BD\u30C3\u30C9\u306E\u30B5\u30DE\u30EA\u30FC" },
{ "doclet.Methods", "\u30E1\u30BD\u30C3\u30C9" },
{ "doclet.Methods_Inherited_From_Class", "\u30AF\u30E9\u30B9\u304B\u3089\u7D99\u627F\u3055\u308C\u305F\u30E1\u30BD\u30C3\u30C9" },
{ "doclet.Methods_Inherited_From_Interface", "\u30A4\u30F3\u30BF\u30D5\u30A7\u30FC\u30B9\u304B\u3089\u7D99\u627F\u3055\u308C\u305F\u30E1\u30BD\u30C3\u30C9" },
{ "doclet.MissingSerialDataTag", "\u30AF\u30E9\u30B9{0}\u306E\u30E1\u30BD\u30C3\u30C9{1}\u306B@serialData\u30BF\u30B0\u304C\u3042\u308A\u307E\u305B\u3093\u3002" },
{ "doclet.MissingSerialTag", "\u30AF\u30E9\u30B9{0}\u306E\u30C7\u30D5\u30A9\u30EB\u30C8\u306E\u76F4\u5217\u5316\u53EF\u80FD\u30D5\u30A3\u30FC\u30EB\u30C9{1}\u306E\u305F\u3081\u306E@serial\u30BF\u30B0\u304C\u3042\u308A\u307E\u305B\u3093\u3002" },
{ "doclet.Modifier", "\u4FEE\u98FE\u5B50" },
{ "doclet.Nested_Class_Summary", "\u30CD\u30B9\u30C8\u3055\u308C\u305F\u30AF\u30E9\u30B9\u306E\u30B5\u30DE\u30EA\u30FC" },
{ "doclet.Nested_Classes", "\u30CD\u30B9\u30C8\u3055\u308C\u305F\u30AF\u30E9\u30B9" },
{ "doclet.Nested_Classes_Interface_Inherited_From_Interface", "\u30A4\u30F3\u30BF\u30D5\u30A7\u30FC\u30B9\u304B\u3089\u7D99\u627F\u3055\u308C\u305F\u30CD\u30B9\u30C8\u3055\u308C\u305F\u30AF\u30E9\u30B9/\u30A4\u30F3\u30BF\u30D5\u30A7\u30FC\u30B9" },
{ "doclet.Nested_Classes_Interfaces_Inherited_From_Class", "\u30AF\u30E9\u30B9\u304B\u3089\u7D99\u627F\u3055\u308C\u305F\u30CD\u30B9\u30C8\u3055\u308C\u305F\u30AF\u30E9\u30B9/\u30A4\u30F3\u30BF\u30D5\u30A7\u30FC\u30B9" },
{ "doclet.No_Public_Classes_To_Document", "\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u5316\u3059\u308Bpublic\u307E\u305F\u306Fprotected\u30AF\u30E9\u30B9\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093\u3002" },
{ "doclet.Notice_taglet_conflict_warn", "\u6CE8\u610F: \u6A19\u6E96\u30BF\u30B0\u3092\u30AA\u30FC\u30D0\u30FC\u30E9\u30A4\u30C9\u3059\u308B\u53EF\u80FD\u6027\u306E\u3042\u308B\u30AB\u30B9\u30BF\u30E0\u30FB\u30BF\u30B0: {0}\u3002\u30AA\u30FC\u30D0\u30FC\u30E9\u30A4\u30C9\u3092\u907F\u3051\u308B\u305F\u3081\u306B\u3001\u30AB\u30B9\u30BF\u30E0\u30FB\u30BF\u30B0\u540D\u306E\u4E2D\u306B\u5C11\u306A\u304F\u3068\u30821\u3064\u306E\u30D4\u30EA\u30AA\u30C9(.)\u3092\u4F7F\u7528\u3057\u3066\u304F\u3060\u3055\u3044\u3002" },
{ "doclet.Notice_taglet_overriden", "\u6CE8\u610F: \u6A19\u6E96\u30BF\u30B0\u3092\u30AA\u30FC\u30D0\u30FC\u30E9\u30A4\u30C9\u3059\u308B\u30AB\u30B9\u30BF\u30E0\u30FB\u30BF\u30B0: {0}" },
{ "doclet.Notice_taglet_registered", "\u767B\u9332\u3055\u308C\u305F\u30BF\u30B0\u30EC\u30C3\u30C8{0} ..." },
{ "doclet.Notice_taglet_unseen", "\u6CE8\u610F: \u975E\u8868\u793A\u306E\u30AB\u30B9\u30BF\u30E0\u30FB\u30BF\u30B0: {0}" },
{ "doclet.Option_conflict", "\u30AA\u30D7\u30B7\u30E7\u30F3{0}\u304C{1}\u3068\u77DB\u76FE\u3057\u307E\u3059" },
{ "doclet.Option_doclint_invalid_arg", "-Xdoclint\u30AA\u30D7\u30B7\u30E7\u30F3\u306E\u5F15\u6570\u304C\u7121\u52B9\u3067\u3059" },
{ "doclet.Option_doclint_no_qualifiers", "\u30A2\u30AF\u30BB\u30B9\u4FEE\u98FE\u5B50\u306F-Xdoclint\u306E\u5F15\u6570\u306B\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093" },
{ "doclet.Option_reuse", "\u30AA\u30D7\u30B7\u30E7\u30F3\u304C\u518D\u4F7F\u7528\u3055\u308C\u3066\u3044\u307E\u3059: {0}" },
{ "doclet.Other_Packages", "\u305D\u306E\u4ED6\u306E\u30D1\u30C3\u30B1\u30FC\u30B8" },
{ "doclet.Package_Summary", "\u30D1\u30C3\u30B1\u30FC\u30B8\u306E\u30B5\u30DE\u30EA\u30FC" },
{ "doclet.Package_class_and_interface_descriptions", "\u30D1\u30C3\u30B1\u30FC\u30B8\u3001\u30AF\u30E9\u30B9\u304A\u3088\u3073\u30A4\u30F3\u30BF\u30D5\u30A7\u30FC\u30B9\u306E\u8AAC\u660E" },
{ "doclet.Package_private", "(package private)" },
{ "doclet.Packages", "\u30D1\u30C3\u30B1\u30FC\u30B8" },
{ "doclet.Parameters", "\u30D1\u30E9\u30E1\u30FC\u30BF:" },
{ "doclet.Parameters_dup_warn", "\u30D1\u30E9\u30E1\u30FC\u30BF\"{0}\"\u304C2\u56DE\u4EE5\u4E0A\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u5316\u3055\u308C\u3066\u3044\u307E\u3059\u3002" },
{ "doclet.Parameters_warn", "@param argument \"{0}\"\u306F\u30D1\u30E9\u30E1\u30FC\u30BF\u540D\u3067\u306F\u3042\u308A\u307E\u305B\u3093\u3002" },
{ "doclet.Profile_Summary", "\u30D7\u30ED\u30D5\u30A1\u30A4\u30EB\u30FB\u30B5\u30DE\u30EA\u30FC" },
{ "doclet.Profiles", "\u30D7\u30ED\u30D5\u30A1\u30A4\u30EB" },
{ "doclet.Properties", "\u30D7\u30ED\u30D1\u30C6\u30A3" },
{ "doclet.Properties_Inherited_From_Class", "\u30AF\u30E9\u30B9\u304B\u3089\u7D99\u627F\u3055\u308C\u305F\u30D7\u30ED\u30D1\u30C6\u30A3" },
{ "doclet.Properties_Inherited_From_Interface", "\u30A4\u30F3\u30BF\u30D5\u30A7\u30FC\u30B9\u304B\u3089\u7D99\u627F\u3055\u308C\u305F\u30D7\u30ED\u30D1\u30C6\u30A3" },
{ "doclet.Property", "\u30D7\u30ED\u30D1\u30C6\u30A3" },
{ "doclet.PropertyDescription", "\u30D7\u30ED\u30D1\u30C6\u30A3\u306E\u8AAC\u660E:" },
{ "doclet.PropertyGetter", "\u30D7\u30ED\u30D1\u30C6\u30A3\u306E\u5024\u3092\u53D6\u5F97\u3057\u307E\u3059" },
{ "doclet.PropertyGetterWithName", "\u30D7\u30ED\u30D1\u30C6\u30A3{0}\u306E\u5024\u3092\u53D6\u5F97\u3057\u307E\u3059\u3002" },
{ "doclet.PropertySetter", "\u30D7\u30ED\u30D1\u30C6\u30A3\u306E\u5024\u3092\u8A2D\u5B9A\u3057\u307E\u3059" },
{ "doclet.PropertySetterWithName", "\u30D7\u30ED\u30D1\u30C6\u30A3{0}\u306E\u5024\u3092\u8A2D\u5B9A\u3057\u307E\u3059\u3002" },
{ "doclet.Property_Detail", "\u30D7\u30ED\u30D1\u30C6\u30A3\u306E\u8A73\u7D30" },
{ "doclet.Property_Summary", "\u30D7\u30ED\u30D1\u30C6\u30A3\u306E\u30B5\u30DE\u30EA\u30FC" },
{ "doclet.Return_tag_on_void_method", "\u623B\u308A\u5024\u306E\u578B\u304Cvoid\u306E\u30E1\u30BD\u30C3\u30C9\u3067\u306F@return\u30BF\u30B0\u3092\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093\u3002" },
{ "doclet.Returns", "\u623B\u308A\u5024:" },
{ "doclet.See", "\u53C2\u7167\u5148:" },
{ "doclet.See_Also", "\u95A2\u9023\u9805\u76EE:" },
{ "doclet.SerialData", "\u30B7\u30EA\u30A2\u30EB\u30FB\u30C7\u30FC\u30BF:" },
{ "doclet.Serializable_no_customization", "readObject\u307E\u305F\u306FwriteObject\u30E1\u30BD\u30C3\u30C9\u304C\u5BA3\u8A00\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002" },
{ "doclet.Serialized_Form", "\u76F4\u5217\u5316\u3055\u308C\u305F\u5F62\u5F0F" },
{ "doclet.Serialized_Form_class", "\u76F4\u5217\u5316\u306E\u6982\u8981" },
{ "doclet.Serialized_Form_fields", "\u76F4\u5217\u5316\u3055\u308C\u305F\u30D5\u30A3\u30FC\u30EB\u30C9" },
{ "doclet.Serialized_Form_methods", "\u76F4\u5217\u5316\u30E1\u30BD\u30C3\u30C9" },
{ "doclet.Since", "\u5C0E\u5165\u3055\u308C\u305F\u30D0\u30FC\u30B8\u30E7\u30F3:" },
{ "doclet.Static_Methods", "static\u30E1\u30BD\u30C3\u30C9" },
{ "doclet.Throws", "\u4F8B\u5916:" },
{ "doclet.Toolkit_Usage_Violation", "\u30C9\u30C3\u30AF\u30EC\u30C3\u30C8\u30FB\u30C4\u30FC\u30EB\u30FB\u30AD\u30C3\u30C8\u306F{0}\u306B\u3088\u3063\u3066\u306E\u307F\u4F7F\u7528\u3055\u308C\u307E\u3059" },
{ "doclet.Type", "\u30BF\u30A4\u30D7" },
{ "doclet.TypeParameters", "\u578B\u30D1\u30E9\u30E1\u30FC\u30BF:" },
{ "doclet.Type_Parameters_dup_warn", "\u578B\u30D1\u30E9\u30E1\u30FC\u30BF\"{0}\"\u304C2\u56DE\u4EE5\u4E0A\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u5316\u3055\u308C\u3066\u3044\u307E\u3059\u3002" },
{ "doclet.Type_Parameters_warn", "@param argument \"{0}\"\u306F\u578B\u30D1\u30E9\u30E1\u30FC\u30BF\u540D\u3067\u306F\u3042\u308A\u307E\u305B\u3093\u3002" },
{ "doclet.Unable_to_create_directory_0", "\u30C7\u30A3\u30EC\u30AF\u30C8\u30EA{0}\u3092\u4F5C\u6210\u3067\u304D\u307E\u305B\u3093" },
{ "doclet.UnknownTag", "{0}\u306F\u4E0D\u660E\u306A\u30BF\u30B0\u3067\u3059\u3002" },
{ "doclet.UnknownTagLowercase", "{0}\u306F\u4E0D\u660E\u306A\u30BF\u30B0\u3067\u3059\u3002\u5927\u6587\u5B57\u3068\u5C0F\u6587\u5B57\u306E\u533A\u5225\u3092\u9664\u3044\u3066\u306F\u65E2\u77E5\u306E\u30BF\u30B0\u3068\u540C\u3058\u3067\u3059\u3002" },
{ "doclet.Use_Table_Summary", "\u8868\u3001{0}\u306E\u30EA\u30B9\u30C8\u304A\u3088\u3073\u8AAC\u660E\u306E\u4F7F\u7528" },
{ "doclet.Value", "\u5024" },
{ "doclet.Version", "\u30D0\u30FC\u30B8\u30E7\u30F3:" },
{ "doclet.annotation_type_optional_members", "\u4EFB\u610F\u8981\u7D20" },
{ "doclet.annotation_type_required_members", "\u5FC5\u9808\u8981\u7D20" },
{ "doclet.annotationtype", "\u6CE8\u91C8\u578B" },
{ "doclet.annotationtypes", "\u6CE8\u91C8\u578B" },
{ "doclet.class", "\u30AF\u30E9\u30B9" },
{ "doclet.classes", "\u30AF\u30E9\u30B9" },
{ "doclet.constructors", "\u30B3\u30F3\u30B9\u30C8\u30E9\u30AF\u30BF" },
{ "doclet.dest_dir_create", "\u5B9B\u5148\u30C7\u30A3\u30EC\u30AF\u30C8\u30EA\u306E\u4F5C\u6210\u4E2D: \"{0}\"" },
{ "doclet.destination_directory_not_directory_0", "\u8EE2\u9001\u5148\u30C7\u30A3\u30EC\u30AF\u30C8\u30EA{0}\u306F\u30C7\u30A3\u30EC\u30AF\u30C8\u30EA\u3067\u306F\u3042\u308A\u307E\u305B\u3093" },
{ "doclet.destination_directory_not_writable_0", "\u8EE2\u9001\u5148\u30C7\u30A3\u30EC\u30AF\u30C8\u30EA{0}\u306F\u66F8\u8FBC\u307F\u53EF\u80FD\u3067\u306F\u3042\u308A\u307E\u305B\u3093" },
{ "doclet.enum", "\u5217\u6319" },
{ "doclet.enum_constants", "\u5217\u6319\u578B\u5B9A\u6570" },
{ "doclet.enum_valueof_doc.main", "\n\u6307\u5B9A\u3057\u305F\u540D\u524D\u3092\u6301\u3064\u3053\u306E\u578B\u306E\u5217\u6319\u578B\u5B9A\u6570\u3092\u8FD4\u3057\u307E\u3059\u3002\n\u6587\u5B57\u5217\u306F\u3001\u3053\u306E\u578B\u306E\u5217\u6319\u578B\u5B9A\u6570\u3092\u5BA3\u8A00\u3059\u308B\u306E\u306B\u4F7F\u7528\u3057\u305F\u8B58\u5225\u5B50\u3068<i>\u6B63\u78BA\u306B</i>\n\u4E00\u81F4\u3057\u3066\u3044\u308B\u5FC5\u8981\u304C\u3042\u308A\u307E\u3059\u3002\n(\u4F59\u5206\u306A\u7A7A\u767D\u6587\u5B57\u3092\u542B\u3081\u308B\u3053\u3068\u306F\u3067\u304D\u307E\u305B\u3093\u3002)\n" },
{ "doclet.enum_valueof_doc.param_name", "\u8FD4\u3055\u308C\u308B\u5217\u6319\u578B\u5B9A\u6570\u306E\u540D\u524D\u3002" },
{ "doclet.enum_valueof_doc.return", "\u6307\u5B9A\u3057\u305F\u540D\u524D\u306E\u5217\u6319\u578B\u5B9A\u6570" },
{ "doclet.enum_valueof_doc.throws_ila", "\u3053\u306E\u5217\u6319\u578B\u306B\u3001\u6307\u5B9A\u3057\u305F\u540D\u524D\u306E\u5B9A\u6570\u304C\u306A\u3044\u5834\u5408" },
{ "doclet.enum_valueof_doc.throws_npe", "\u5F15\u6570\u304Cnull\u306E\u5834\u5408" },
{ "doclet.enum_values_doc.main", "\n\u3053\u306E\u5217\u6319\u578B\u306E\u5B9A\u6570\u3092\u542B\u3080\u914D\u5217\u3092\u5BA3\u8A00\u3055\u308C\u3066\u3044\u308B\u9806\u5E8F\u3067\u8FD4\u3057\u307E\u3059\u3002\n\u3053\u306E\u30E1\u30BD\u30C3\u30C9\u306F\u6B21\u306E\u3088\u3046\u306B\u3057\u3066\u5B9A\u6570\u3092\u53CD\u5FA9\u3059\u308B\u305F\u3081\u306B\n\u4F7F\u7528\u3067\u304D\u307E\u3059:\n<pre>\nfor({0} c: {0}.values())\n&nbsp; System.out.println(c);\n</pre>\n" },
{ "doclet.enum_values_doc.return", "\n\u3053\u306E\u5217\u6319\u578B\u306E\u5B9A\u6570\u3092\u542B\u3080\u3001\u5BA3\u8A00\u3055\u308C\u3066\u3044\u308B\u9806\u5E8F\u3067\u306E\u914D\u5217" },
{ "doclet.enums", "\u5217\u6319" },
{ "doclet.error", "\u30A8\u30E9\u30FC" },
{ "doclet.errors", "\u30A8\u30E9\u30FC" },
{ "doclet.exception", "\u4F8B\u5916" },
{ "doclet.exception_encountered", "{0}\u3092\u691C\u51FA\n\t\u30D5\u30A1\u30A4\u30EB\u306E\u4F5C\u6210\u4E2D: {1}" },
{ "doclet.exceptions", "\u4F8B\u5916" },
{ "doclet.fields", "\u30D5\u30A3\u30FC\u30EB\u30C9" },
{ "doclet.in", "{1}\u306E{0}" },
{ "doclet.interface", "\u30A4\u30F3\u30BF\u30D5\u30A7\u30FC\u30B9" },
{ "doclet.interfaces", "\u30A4\u30F3\u30BF\u30D5\u30A7\u30FC\u30B9" },
{ "doclet.javafx_tag_misuse", "\u30BF\u30B0@propertyGetter\u3001@propertySetter\u304A\u3088\u3073@propertyDescription\u306F\u3001JavaFX\u306E\u30D7\u30ED\u30D1\u30C6\u30A3getter\u3068setter\u306E\u307F\u3067\u4F7F\u7528\u3067\u304D\u307E\u3059\u3002" },
{ "doclet.malformed_html_link_tag", "<a> \u30BF\u30B0\u306E\u5F62\u5F0F\u304C\u4E0D\u6B63:\n\"{0}\"" },
{ "doclet.methods", "\u30E1\u30BD\u30C3\u30C9" },
{ "doclet.nested_classes", "\u30CD\u30B9\u30C8\u3055\u308C\u305F\u30AF\u30E9\u30B9" },
{ "doclet.noInheritedDoc", "@inheritDoc\u304C\u4F7F\u7528\u3055\u308C\u3066\u3044\u307E\u3059\u304C\u3001{0}\u306F\u3069\u306E\u30E1\u30BD\u30C3\u30C9\u3082\u30AA\u30FC\u30D0\u30FC\u30E9\u30A4\u30C9\u307E\u305F\u306F\u5B9F\u88C5\u3057\u3066\u3044\u307E\u305B\u3093\u3002" },
{ "doclet.packages", "\u30D1\u30C3\u30B1\u30FC\u30B8" },
{ "doclet.perform_copy_exception_encountered", "\u30B3\u30D4\u30FC\u5B9F\u884C\u4E2D\u306B{0}\u3092\n\u691C\u51FA\u3057\u307E\u3057\u305F\u3002" },
{ "doclet.profiles", "\u30D7\u30ED\u30D5\u30A1\u30A4\u30EB" },
{ "doclet.properties", "\u30D7\u30ED\u30D1\u30C6\u30A3" },
{ "doclet.sourcetab_warning", "-sourcetab\u306E\u5F15\u6570\u306F0\u3088\u308A\u5927\u304D\u3044\u6574\u6570\u3067\u3042\u308B\u5FC5\u8981\u304C\u3042\u308A\u307E\u3059\u3002" },
{ "doclet.subclasses", "\u30B5\u30D6\u30AF\u30E9\u30B9" },
{ "doclet.subinterfaces", "\u30B5\u30D6\u30A4\u30F3\u30BF\u30D5\u30A7\u30FC\u30B9" },
{ "doclet.tag_misuse", "{0}\u30BF\u30B0\u306F{1}\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u5185\u3067\u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093\u3002\u4F7F\u7528\u3067\u304D\u308B\u306E\u306F\u6B21\u306E\u30BF\u30A4\u30D7\u306E\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u5185\u306E\u307F\u3067\u3059: {2}\u3002" },
{ "doclet.value_tag_invalid_constant", "@value\u30BF\u30B0({0}\u3092\u53C2\u7167\u3057\u3066\u3044\u308B)\u306F\u5B9A\u6570\u5185\u3067\u306E\u307F\u4F7F\u7528\u3067\u304D\u307E\u3059\u3002" },
{ "doclet.value_tag_invalid_reference", "{0}(@value\u30BF\u30B0\u306B\u3088\u308A\u53C2\u7167\u3055\u308C\u3066\u3044\u308B)\u306F\u4E0D\u660E\u306A\u53C2\u7167\u3067\u3059\u3002" },
{ "doclet.value_tag_invalid_use", "@value\u30BF\u30B0\u306F\u3053\u3053\u3067\u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093\u3002" },
};
}
}

196
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/resources/doclets_zh_CN.java Normal file
View File

@@ -0,0 +1,196 @@
package com.sun.tools.doclets.internal.toolkit.resources;
public final class doclets_zh_CN extends java.util.ListResourceBundle {
protected final Object[][] getContents() {
return new Object[][] {
{ "doclet.0_and_1", "{0}\u548C{1}" },
{ "doclet.Abstract_Methods", "\u62BD\u8C61\u65B9\u6CD5" },
{ "doclet.All_Classes", "\u6240\u6709\u7C7B" },
{ "doclet.All_Implemented_Interfaces", "\u6240\u6709\u5DF2\u5B9E\u73B0\u7684\u63A5\u53E3:" },
{ "doclet.All_Methods", "\u6240\u6709\u65B9\u6CD5" },
{ "doclet.All_Superinterfaces", "\u6240\u6709\u8D85\u7EA7\u63A5\u53E3:" },
{ "doclet.All_classes_and_interfaces", "\u6240\u6709\u7C7B\u548C\u63A5\u53E3 (\u9664\u4E86\u975E\u9759\u6001\u5D4C\u5957\u7C7B\u578B)" },
{ "doclet.AnnotationType", "\u6CE8\u91CA\u7C7B\u578B" },
{ "doclet.AnnotationTypes", "\u6CE8\u91CA\u7C7B\u578B" },
{ "doclet.Annotation_Type_Member", "\u6CE8\u91CA\u7C7B\u578B\u5143\u7D20" },
{ "doclet.Annotation_Type_Member_Detail", "\u5143\u7D20\u8BE6\u7EC6\u8D44\u6599" },
{ "doclet.Annotation_Type_Optional_Member", "\u53EF\u9009\u5143\u7D20" },
{ "doclet.Annotation_Type_Optional_Member_Summary", "\u53EF\u9009\u5143\u7D20\u6982\u8981" },
{ "doclet.Annotation_Type_Optional_Members", "\u53EF\u9009\u5143\u7D20" },
{ "doclet.Annotation_Type_Required_Member", "\u5FC5\u9700\u7684\u5143\u7D20" },
{ "doclet.Annotation_Type_Required_Member_Summary", "\u5FC5\u9700\u5143\u7D20\u6982\u8981" },
{ "doclet.Annotation_Type_Required_Members", "\u6240\u9700\u5143\u7D20" },
{ "doclet.Annotation_Types_Summary", "\u6CE8\u91CA\u7C7B\u578B\u6982\u8981" },
{ "doclet.Author", "\u4F5C\u8005:" },
{ "doclet.Building_Index", "\u6B63\u5728\u6784\u5EFA\u6240\u6709\u7A0B\u5E8F\u5305\u548C\u7C7B\u7684\u7D22\u5F15..." },
{ "doclet.Building_Index_For_All_Classes", "\u6B63\u5728\u6784\u5EFA\u6240\u6709\u7C7B\u7684\u7D22\u5F15..." },
{ "doclet.Building_Tree", "\u6B63\u5728\u6784\u5EFA\u6240\u6709\u7A0B\u5E8F\u5305\u548C\u7C7B\u7684\u6811..." },
{ "doclet.Class", "\u7C7B" },
{ "doclet.Class_0_extends_implements_serializable", "\u7C7B{0}\u6269\u5C55{1}\u5B9E\u73B0\u53EF\u5E8F\u5217\u5316" },
{ "doclet.Class_0_implements_serializable", "\u7C7B{0}\u5B9E\u73B0\u53EF\u5E8F\u5217\u5316" },
{ "doclet.Class_Summary", "\u7C7B\u6982\u8981" },
{ "doclet.Classes", "\u7C7B" },
{ "doclet.Concrete_Methods", "\u5177\u4F53\u65B9\u6CD5" },
{ "doclet.ConstantField", "\u5E38\u91CF\u5B57\u6BB5" },
{ "doclet.Constants_Summary", "\u5E38\u91CF\u5B57\u6BB5\u503C" },
{ "doclet.Constants_Table_Summary", "{0}\u8868, \u5217\u8868\u5E38\u91CF\u5B57\u6BB5\u548C\u503C" },
{ "doclet.Constructor", "\u6784\u9020\u5668" },
{ "doclet.Constructor_Detail", "\u6784\u9020\u5668\u8BE6\u7EC6\u8D44\u6599" },
{ "doclet.Constructor_Summary", "\u6784\u9020\u5668\u6982\u8981" },
{ "doclet.Constructors", "\u6784\u9020\u5668" },
{ "doclet.Copy_Overwrite_warning", "\u672A\u5C06\u6587\u4EF6{0}\u590D\u5236\u5230 {1}, \u56E0\u4E3A\u73B0\u6709\u6587\u4EF6\u5177\u6709\u76F8\u540C\u540D\u79F0..." },
{ "doclet.Copying_File_0_To_Dir_1", "\u6B63\u5728\u5C06\u6587\u4EF6{0}\u590D\u5236\u5230\u76EE\u5F55 {1}..." },
{ "doclet.Copying_File_0_To_File_1", "\u6B63\u5728\u5C06\u6587\u4EF6{0}\u590D\u5236\u5230\u6587\u4EF6{1}..." },
{ "doclet.Default", "\u9ED8\u8BA4\u503C:" },
{ "doclet.DefaultValue", "\u9ED8\u8BA4\u503C:" },
{ "doclet.Default_Methods", "\u9ED8\u8BA4\u65B9\u6CD5" },
{ "doclet.Deprecated", "\u5DF2\u8FC7\u65F6\u3002" },
{ "doclet.Deprecated_Methods", "\u5DF2\u8FC7\u65F6\u7684\u65B9\u6CD5" },
{ "doclet.Description", "\u8BF4\u660E" },
{ "doclet.Encoding_not_supported", "\u4E0D\u652F\u6301\u7F16\u7801: {0}" },
{ "doclet.Enum", "\u679A\u4E3E" },
{ "doclet.Enum_Constant", "\u679A\u4E3E\u5E38\u91CF" },
{ "doclet.Enum_Constant_Detail", "\u679A\u4E3E\u5E38\u91CF\u8BE6\u7EC6\u8D44\u6599" },
{ "doclet.Enum_Constant_Summary", "\u679A\u4E3E\u5E38\u91CF\u6982\u8981" },
{ "doclet.Enum_Constants", "\u679A\u4E3E\u5E38\u91CF" },
{ "doclet.Enum_Summary", "\u679A\u4E3E\u6982\u8981" },
{ "doclet.Enums", "\u679A\u4E3E" },
{ "doclet.Error", "\u9519\u8BEF" },
{ "doclet.Error_Summary", "\u9519\u8BEF\u6982\u8981" },
{ "doclet.Error_invalid_custom_tag_argument", "\u9519\u8BEF - \u5BF9\u4E8E -tag \u9009\u9879, {0}\u662F\u65E0\u6548\u53C2\u6570..." },
{ "doclet.Error_taglet_not_registered", "\u9519\u8BEF - \u5C1D\u8BD5\u6CE8\u518C Taglet {1}\u65F6\u629B\u51FA\u5F02\u5E38\u9519\u8BEF{0}..." },
{ "doclet.Errors", "\u9519\u8BEF" },
{ "doclet.Exception", "\u5F02\u5E38\u9519\u8BEF" },
{ "doclet.Exception_Summary", "\u5F02\u5E38\u9519\u8BEF\u6982\u8981" },
{ "doclet.Exceptions", "\u5F02\u5E38\u9519\u8BEF" },
{ "doclet.Factory", "\u5DE5\u5382:" },
{ "doclet.Field", "\u5B57\u6BB5" },
{ "doclet.Field_Detail", "\u5B57\u6BB5\u8BE6\u7EC6\u8D44\u6599" },
{ "doclet.Field_Summary", "\u5B57\u6BB5\u6982\u8981" },
{ "doclet.Fields", "\u5B57\u6BB5" },
{ "doclet.Fields_Inherited_From_Class", "\u4ECE\u7C7B\u7EE7\u627F\u7684\u5B57\u6BB5" },
{ "doclet.Fields_Inherited_From_Interface", "\u4ECE\u63A5\u53E3\u7EE7\u627F\u7684\u5B57\u6BB5" },
{ "doclet.File_not_found", "\u627E\u4E0D\u5230\u6587\u4EF6: {0}" },
{ "doclet.Generating_0", "\u6B63\u5728\u751F\u6210{0}..." },
{ "doclet.Groupname_already_used", "\u5728 -group \u9009\u9879\u4E2D, groupname \u5DF2\u4F7F\u7528: {0}" },
{ "doclet.Instance_Methods", "\u5B9E\u4F8B\u65B9\u6CD5" },
{ "doclet.Interface", "\u63A5\u53E3" },
{ "doclet.Interface_Summary", "\u63A5\u53E3\u6982\u8981" },
{ "doclet.Interfaces", "\u63A5\u53E3" },
{ "doclet.JavaScript_in_option", "{0} \u7684\u53C2\u6570\u5305\u542B JavaScript\u3002\n\u4F7F\u7528 --allow-script-in-comments \u53EF\u5141\u8BB8\u4F7F\u7528 JavaScript\u3002" },
{ "doclet.Member_Table_Summary", "{0}\u8868, \u5217\u8868{1}\u548C\u89E3\u91CA" },
{ "doclet.Method", "\u65B9\u6CD5" },
{ "doclet.Method_Detail", "\u65B9\u6CD5\u8BE6\u7EC6\u8D44\u6599" },
{ "doclet.Method_Summary", "\u65B9\u6CD5\u6982\u8981" },
{ "doclet.Methods", "\u65B9\u6CD5" },
{ "doclet.Methods_Inherited_From_Class", "\u4ECE\u7C7B\u7EE7\u627F\u7684\u65B9\u6CD5" },
{ "doclet.Methods_Inherited_From_Interface", "\u4ECE\u63A5\u53E3\u7EE7\u627F\u7684\u65B9\u6CD5" },
{ "doclet.MissingSerialDataTag", "\u5728\u7C7B{0}\u4E2D, \u65B9\u6CD5{1}\u4E2D\u7F3A\u5C11 @serialData \u6807\u8BB0\u3002" },
{ "doclet.MissingSerialTag", "\u5728\u7C7B{0}\u4E2D, \u9ED8\u8BA4\u7684\u53EF\u5E8F\u5217\u5316\u5B57\u6BB5{1}\u7F3A\u5C11 @serial \u6807\u8BB0\u3002" },
{ "doclet.Modifier", "\u9650\u5B9A\u7B26" },
{ "doclet.Nested_Class_Summary", "\u5D4C\u5957\u7C7B\u6982\u8981" },
{ "doclet.Nested_Classes", "\u5D4C\u5957\u7C7B" },
{ "doclet.Nested_Classes_Interface_Inherited_From_Interface", "\u4ECE\u63A5\u53E3\u7EE7\u627F\u7684\u5D4C\u5957\u7C7B/\u63A5\u53E3" },
{ "doclet.Nested_Classes_Interfaces_Inherited_From_Class", "\u4ECE\u7C7B\u7EE7\u627F\u7684\u5D4C\u5957\u7C7B/\u63A5\u53E3" },
{ "doclet.No_Public_Classes_To_Document", "\u627E\u4E0D\u5230\u53EF\u4EE5\u6587\u6863\u5316\u7684\u516C\u5171\u6216\u53D7\u4FDD\u62A4\u7684\u7C7B\u3002" },
{ "doclet.Notice_taglet_conflict_warn", "\u6CE8: \u53EF\u80FD\u8986\u76D6\u5C06\u6765\u7684\u6807\u51C6\u6807\u8BB0\u7684\u5B9A\u5236\u6807\u8BB0: {0}\u3002\u4E3A\u4E86\u907F\u514D\u51FA\u73B0\u53EF\u80FD\u7684\u8986\u76D6, \u8BF7\u5728\u5B9A\u5236\u6807\u8BB0\u540D\u79F0\u4E2D\u81F3\u5C11\u4F7F\u7528\u4E00\u4E2A\u53E5\u70B9\u5B57\u7B26 (.)\u3002" },
{ "doclet.Notice_taglet_overriden", "\u6CE8: \u8986\u76D6\u6807\u51C6\u6807\u8BB0\u7684\u5B9A\u5236\u6807\u8BB0: {0}" },
{ "doclet.Notice_taglet_registered", "\u6CE8\u518C\u7684 Taglet {0}..." },
{ "doclet.Notice_taglet_unseen", "\u6CE8: \u627E\u4E0D\u5230\u7684\u5B9A\u5236\u6807\u8BB0: {0}" },
{ "doclet.Option_conflict", "\u9009\u9879{0}\u4E0E{1}\u51B2\u7A81" },
{ "doclet.Option_doclint_invalid_arg", "-Xdoclint \u9009\u9879\u7684\u53C2\u6570\u65E0\u6548" },
{ "doclet.Option_doclint_no_qualifiers", "-Xdoclint \u53C2\u6570\u4E0D\u5141\u8BB8\u4F7F\u7528\u8BBF\u95EE\u9650\u5B9A\u7B26" },
{ "doclet.Option_reuse", "\u91CD\u590D\u4F7F\u7528\u7684\u9009\u9879: {0}" },
{ "doclet.Other_Packages", "\u5176\u4ED6\u7A0B\u5E8F\u5305" },
{ "doclet.Package_Summary", "\u7A0B\u5E8F\u5305\u6982\u8981" },
{ "doclet.Package_class_and_interface_descriptions", "\u7A0B\u5E8F\u5305, \u7C7B\u548C\u63A5\u53E3\u8BF4\u660E" },
{ "doclet.Package_private", "(\u4E13\u7528\u7A0B\u5E8F\u5305)" },
{ "doclet.Packages", "\u7A0B\u5E8F\u5305" },
{ "doclet.Parameters", "\u53C2\u6570:" },
{ "doclet.Parameters_dup_warn", "\u591A\u6B21\u5BF9\u53C2\u6570 \"{0}\" \u8FDB\u884C\u6587\u6863\u5316\u3002" },
{ "doclet.Parameters_warn", "@param argument \"{0}\" \u4E0D\u662F\u53C2\u6570\u540D\u79F0\u3002" },
{ "doclet.Profile_Summary", "\u6982\u8981\u4FE1\u606F\u6982\u8981" },
{ "doclet.Profiles", "\u914D\u7F6E\u6587\u4EF6" },
{ "doclet.Properties", "\u5C5E\u6027" },
{ "doclet.Properties_Inherited_From_Class", "\u4ECE\u7C7B\u7EE7\u627F\u7684\u5C5E\u6027" },
{ "doclet.Properties_Inherited_From_Interface", "\u4ECE\u63A5\u53E3\u7EE7\u627F\u7684\u5C5E\u6027" },
{ "doclet.Property", "\u5C5E\u6027" },
{ "doclet.PropertyDescription", "\u5C5E\u6027\u8BF4\u660E:" },
{ "doclet.PropertyGetter", "\u83B7\u53D6\u5C5E\u6027\u7684\u503C" },
{ "doclet.PropertyGetterWithName", "\u83B7\u53D6\u5C5E\u6027{0}\u7684\u503C\u3002" },
{ "doclet.PropertySetter", "\u8BBE\u7F6E\u5C5E\u6027\u7684\u503C" },
{ "doclet.PropertySetterWithName", "\u8BBE\u7F6E\u5C5E\u6027{0}\u7684\u503C\u3002" },
{ "doclet.Property_Detail", "\u5C5E\u6027\u8BE6\u7EC6\u4FE1\u606F" },
{ "doclet.Property_Summary", "\u5C5E\u6027\u6982\u8981" },
{ "doclet.Return_tag_on_void_method", "\u4E0D\u80FD\u5728\u8FD4\u56DE\u7C7B\u578B\u4E3A\u7A7A\u7684\u65B9\u6CD5\u4E2D\u4F7F\u7528 @return \u6807\u8BB0\u3002" },
{ "doclet.Returns", "\u8FD4\u56DE:" },
{ "doclet.See", "\u8BF7\u53C2\u9605:" },
{ "doclet.See_Also", "\u53E6\u8BF7\u53C2\u9605:" },
{ "doclet.SerialData", "\u5E8F\u5217\u6570\u636E:" },
{ "doclet.Serializable_no_customization", "\u672A\u58F0\u660E readObject \u6216 writeObject \u65B9\u6CD5\u3002" },
{ "doclet.Serialized_Form", "\u5E8F\u5217\u5316\u8868\u683C" },
{ "doclet.Serialized_Form_class", "\u5E8F\u5217\u5316\u6982\u89C8" },
{ "doclet.Serialized_Form_fields", "\u5E8F\u5217\u5316\u5B57\u6BB5" },
{ "doclet.Serialized_Form_methods", "\u5E8F\u5217\u5316\u65B9\u6CD5" },
{ "doclet.Since", "\u4ECE\u4EE5\u4E0B\u7248\u672C\u5F00\u59CB:" },
{ "doclet.Static_Methods", "\u9759\u6001\u65B9\u6CD5" },
{ "doclet.Throws", "\u629B\u51FA:" },
{ "doclet.Toolkit_Usage_Violation", "\u53EA\u6709{0}\u53EF\u4EE5\u4F7F\u7528 Doclet \u5DE5\u5177\u7BB1" },
{ "doclet.Type", "\u7C7B\u578B" },
{ "doclet.TypeParameters", "\u7C7B\u578B\u53C2\u6570:" },
{ "doclet.Type_Parameters_dup_warn", "\u591A\u6B21\u5BF9\u7C7B\u578B\u53C2\u6570 \"{0}\" \u8FDB\u884C\u6587\u6863\u5316\u3002" },
{ "doclet.Type_Parameters_warn", "@param argument \"{0}\" \u4E0D\u662F\u7C7B\u578B\u53C2\u6570\u540D\u79F0\u3002" },
{ "doclet.Unable_to_create_directory_0", "\u65E0\u6CD5\u521B\u5EFA\u76EE\u5F55 {0}" },
{ "doclet.UnknownTag", "{0}\u662F\u672A\u77E5\u6807\u8BB0\u3002" },
{ "doclet.UnknownTagLowercase", "{0}\u662F\u672A\u77E5\u6807\u8BB0 - \u9664\u4E86\u5927\u5C0F\u5199\u4E4B\u5916\u5176\u4ED6\u65B9\u9762\u4E0E\u5DF2\u77E5\u6807\u8BB0\u76F8\u540C\u3002" },
{ "doclet.Use_Table_Summary", "\u4F7F\u7528\u8868, \u5217\u8868{0}\u548C\u89E3\u91CA" },
{ "doclet.Value", "\u503C" },
{ "doclet.Version", "\u7248\u672C:" },
{ "doclet.annotation_type_optional_members", "\u53EF\u9009\u5143\u7D20" },
{ "doclet.annotation_type_required_members", "\u5FC5\u9700\u7684\u5143\u7D20" },
{ "doclet.annotationtype", "\u6CE8\u91CA\u7C7B\u578B" },
{ "doclet.annotationtypes", "\u6CE8\u91CA\u7C7B\u578B" },
{ "doclet.class", "\u7C7B" },
{ "doclet.classes", "\u7C7B" },
{ "doclet.constructors", "\u6784\u9020\u5668" },
{ "doclet.dest_dir_create", "\u6B63\u5728\u521B\u5EFA\u76EE\u6807\u76EE\u5F55: \"{0}\"" },
{ "doclet.destination_directory_not_directory_0", "\u76EE\u6807\u76EE\u5F55\u4E0D\u662F\u76EE\u5F55 {0}" },
{ "doclet.destination_directory_not_writable_0", "\u76EE\u6807\u76EE\u5F55\u4E0D\u53EF\u5199\u5165 {0}" },
{ "doclet.enum", "\u679A\u4E3E" },
{ "doclet.enum_constants", "\u679A\u4E3E\u5E38\u91CF" },
{ "doclet.enum_valueof_doc.main", "\n\u8FD4\u56DE\u5E26\u6709\u6307\u5B9A\u540D\u79F0\u7684\u8BE5\u7C7B\u578B\u7684\u679A\u4E3E\u5E38\u91CF\u3002\n\u5B57\u7B26\u4E32\u5FC5\u987B\u4E0E\u7528\u4E8E\u58F0\u660E\u8BE5\u7C7B\u578B\u7684\u679A\u4E3E\u5E38\u91CF\u7684\n\u6807\u8BC6\u7B26<i>\u5B8C\u5168</i>\u5339\u914D\u3002(\u4E0D\u5141\u8BB8\u6709\u591A\u4F59\n\u7684\u7A7A\u683C\u5B57\u7B26\u3002)" },
{ "doclet.enum_valueof_doc.param_name", "\u8981\u8FD4\u56DE\u7684\u679A\u4E3E\u5E38\u91CF\u7684\u540D\u79F0\u3002" },
{ "doclet.enum_valueof_doc.return", "\u8FD4\u56DE\u5E26\u6709\u6307\u5B9A\u540D\u79F0\u7684\u679A\u4E3E\u5E38\u91CF" },
{ "doclet.enum_valueof_doc.throws_ila", "\u5982\u679C\u8BE5\u679A\u4E3E\u7C7B\u578B\u6CA1\u6709\u5E26\u6709\u6307\u5B9A\u540D\u79F0\u7684\u5E38\u91CF" },
{ "doclet.enum_valueof_doc.throws_npe", "\u5982\u679C\u53C2\u6570\u4E3A\u7A7A\u503C" },
{ "doclet.enum_values_doc.main", "\n\u6309\u7167\u58F0\u660E\u8BE5\u679A\u4E3E\u7C7B\u578B\u7684\u5E38\u91CF\u7684\u987A\u5E8F, \u8FD4\u56DE\n\u5305\u542B\u8FD9\u4E9B\u5E38\u91CF\u7684\u6570\u7EC4\u3002\u8BE5\u65B9\u6CD5\u53EF\u7528\u4E8E\u8FED\u4EE3\n\u5E38\u91CF, \u5982\u4E0B\u6240\u793A:\n<pre>\nfor ({0} c : {0}.values())\n&nbsp; System.out.println(c);\n</pre>" },
{ "doclet.enum_values_doc.return", "\n\u6309\u7167\u58F0\u660E\u8BE5\u679A\u4E3E\u7C7B\u578B\u7684\u5E38\u91CF\u7684\u987A\u5E8F\u8FD4\u56DE\u7684\u5305\u542B\u8FD9\u4E9B\u5E38\u91CF\u7684\u6570\u7EC4" },
{ "doclet.enums", "\u679A\u4E3E" },
{ "doclet.error", "\u9519\u8BEF" },
{ "doclet.errors", "\u9519\u8BEF" },
{ "doclet.exception", "\u5F02\u5E38\u9519\u8BEF" },
{ "doclet.exception_encountered", "\u5C1D\u8BD5\u521B\u5EFA\u6587\u4EF6{1}\u65F6 \n\t\u9047\u5230{0}" },
{ "doclet.exceptions", "\u5F02\u5E38\u9519\u8BEF" },
{ "doclet.fields", "\u5B57\u6BB5" },
{ "doclet.in", "{1}\u4E2D\u7684{0}" },
{ "doclet.interface", "\u63A5\u53E3" },
{ "doclet.interfaces", "\u63A5\u53E3" },
{ "doclet.javafx_tag_misuse", "\u6807\u8BB0 @propertyGetter, @propertySetter \u548C @propertyDescription \u53EA\u80FD\u5728 JavaFX \u5C5E\u6027 getter \u548C setter \u4E2D\u4F7F\u7528\u3002" },
{ "doclet.malformed_html_link_tag", "<a> \u6807\u8BB0\u683C\u5F0F\u9519\u8BEF: \n\"{0}\"" },
{ "doclet.methods", "\u65B9\u6CD5" },
{ "doclet.nested_classes", "\u5D4C\u5957\u7C7B" },
{ "doclet.noInheritedDoc", "\u4F7F\u7528\u4E86 @inheritDoc, \u4F46{0}\u672A\u8986\u76D6\u6216\u5B9E\u73B0\u4EFB\u4F55\u65B9\u6CD5\u3002" },
{ "doclet.packages", "\u7A0B\u5E8F\u5305" },
{ "doclet.perform_copy_exception_encountered", "\u6267\u884C\u590D\u5236\u65F6 \n\u9047\u5230{0}\u3002" },
{ "doclet.profiles", "\u914D\u7F6E\u6587\u4EF6" },
{ "doclet.properties", "\u5C5E\u6027" },
{ "doclet.sourcetab_warning", "-sourcetab \u7684\u53C2\u6570\u5FC5\u987B\u662F\u5927\u4E8E 0 \u7684\u6574\u6570\u3002" },
{ "doclet.subclasses", "\u5B50\u7C7B" },
{ "doclet.subinterfaces", "\u5B50\u63A5\u53E3" },
{ "doclet.tag_misuse", "\u4E0D\u80FD\u5728{1}\u6587\u6863\u4E2D\u4F7F\u7528\u6807\u8BB0{0}\u3002\u53EA\u80FD\u5728\u4EE5\u4E0B\u7C7B\u578B\u7684\u6587\u6863\u4E2D\u4F7F\u7528\u8BE5\u6807\u8BB0: {2}\u3002" },
{ "doclet.value_tag_invalid_constant", "@value \u6807\u8BB0 (\u5F15\u7528{0}) \u53EA\u80FD\u5728\u5E38\u91CF\u4E2D\u4F7F\u7528\u3002" },
{ "doclet.value_tag_invalid_reference", "{0} (\u7531 @value \u6807\u8BB0\u5F15\u7528) \u4E3A\u672A\u77E5\u5F15\u7528\u3002" },
{ "doclet.value_tag_invalid_use", "\u6B64\u5904\u4E0D\u80FD\u4F7F\u7528 @value \u6807\u8BB0\u3002" },
};
}
}

95
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/BaseExecutableMemberTaglet.java Normal file
View File

@@ -0,0 +1,95 @@
/*
* Copyright (c) 2001, 2012, 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 com.sun.tools.doclets.internal.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
* @since 1.4
*/
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 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;
}
}

49
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/BaseInlineTaglet.java Normal file
View File

@@ -0,0 +1,49 @@
/*
* Copyright (c) 2001, 2012, 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 com.sun.tools.doclets.internal.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
* @since 1.4
*/
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;
}
}

111
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/BasePropertyTaglet.java Normal file
View File

@@ -0,0 +1,111 @@
/*
* Copyright (c) 2001, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
import com.sun.javadoc.Tag;
import com.sun.tools.doclets.internal.toolkit.Content;
/**
* An abstract class that implements the {@link Taglet} interface and
* serves as a base for JavaFX property getter and setter taglets.
*
* <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 abstract class BasePropertyTaglet extends BaseTaglet {
public BasePropertyTaglet() {
}
/**
* This method returns the text to be put in the resulting javadoc before
* the property name.
*
* @param tagletWriter the taglet writer for output
* @return the string to be put in the resulting javadoc.
*/
abstract String getText(TagletWriter tagletWriter);
/**
* Given the <code>Tag</code> representation of this custom
* tag, return its string representation, which is output
* to the generated page.
* @param tag the <code>Tag</code> representation of this custom tag.
* @param tagletWriter the taglet writer for output.
* @return the TagletOutput representation of this <code>Tag</code>.
*/
public Content getTagletOutput(Tag tag, TagletWriter tagletWriter) {
return tagletWriter.propertyTagOutput(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 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;
}
}

145
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/BaseTaglet.java Normal file
View File

@@ -0,0 +1,145 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.Content;
/**
* An abstract class for 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.
* This code and its internal interfaces are subject to change or
* deletion without notice.</b>
*
* @author Jamie Ho
* @since 1.4
*/
public abstract class BaseTaglet implements Taglet {
protected String name = "Default";
/**
* 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 true;
}
/**
* 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 true;
}
/**
* 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
* otherwise.
*/
public boolean inMethod() {
return true;
}
/**
* 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
* otherwise.
*/
public boolean inOverview() {
return true;
}
/**
* 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 true;
}
/**
* 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 true;
}
/**
* 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;
}
/**
* Return the name of this custom tag.
* @return the name of this custom tag.
*/
public String getName() {
return name;
}
/**
* {@inheritDoc}
* @throws IllegalArgumentException thrown when the method is not supported by the taglet.
*/
public Content getTagletOutput(Tag tag, TagletWriter writer) {
throw new IllegalArgumentException("Method not supported in taglet " + getName() + ".");
}
/**
* {@inheritDoc}
* @throws IllegalArgumentException thrown when the method is not supported by the taglet.
*/
public Content getTagletOutput(Doc holder, TagletWriter writer) {
throw new IllegalArgumentException("Method not supported in taglet " + getName() + ".");
}
}

71
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/CodeTaglet.java Normal file
View File

@@ -0,0 +1,71 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
import java.util.Map;
import com.sun.javadoc.Tag;
import com.sun.tools.doclets.internal.toolkit.Content;
/**
* An inline Taglet used to denote literal code fragments.
* The enclosed text is interpreted as not containing HTML markup or
* nested javadoc tags, and is rendered in a font suitable for code.
*
* <p> The tag {@code {@code ...}} is equivalent to
* {@code <code>{@literal ...}</code>}.
* For example, the text:
* <blockquote> The type {@code {@code List<P>}} </blockquote>
* displays as:
* <blockquote> The type {@code List<P>} </blockquote>
*
* <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 Scott Seligman
* @since 1.5
*/
public class CodeTaglet extends BaseInlineTaglet {
private static final String NAME = "code";
public static void register(Map<String, Taglet> map) {
map.remove(NAME);
map.put(NAME, new CodeTaglet());
}
public String getName() {
return NAME;
}
/**
* {@inheritDoc}
*/
public Content getTagletOutput(Tag tag, TagletWriter writer) {
return writer.codeTagOutput(tag);
}
}

55
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/DeprecatedTaglet.java Normal file
View File

@@ -0,0 +1,55 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.Content;
/**
* A taglet that represents the @deprecated 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>
*
* @author Jamie Ho
* @since 1.5
*/
public class DeprecatedTaglet extends BaseTaglet{
public DeprecatedTaglet() {
name = "deprecated";
}
/**
* {@inheritDoc}
*/
public Content getTagletOutput(Doc holder, TagletWriter writer) {
return writer.deprecatedTagOutput(holder);
}
}

67
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/DocRootTaglet.java Normal file
View File

@@ -0,0 +1,67 @@
/*
* Copyright (c) 2001, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.Content;
/**
* An inline Taglet representing {&#064;docRoot}. This taglet is
* used to get the relative path to the document's root output
* directory.
*
* <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
* @author Doug Kramer
* @since 1.4
*/
public class DocRootTaglet extends BaseInlineTaglet {
/**
* Construct a new DocRootTaglet.
*/
public DocRootTaglet() {
name = "docRoot";
}
/**
* 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 tag a tag representing the custom tag.
* @param writer a {@link TagletWriter} Taglet writer.
* @return the string representation of this <code>Tag</code>.
*/
public Content getTagletOutput(Tag tag, TagletWriter writer) {
return writer.getDocRootOutput();
}
}

171
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/InheritDocTaglet.java Normal file
View File

@@ -0,0 +1,171 @@
/*
* Copyright (c) 2001, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.Configuration;
import com.sun.tools.doclets.internal.toolkit.Content;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* An inline Taglet representing the <b>inheritDoc</b> tag. This tag should only
* be used with a method. It is used to inherit documentation from overriden
* and implemented methods.
*
* <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
* @since 1.4
*/
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}";
/**
* Construct a new InheritDocTaglet.
*/
public InheritDocTaglet () {
name = "inheritDoc";
}
/**
* 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 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.
*
* @param writer the writer that is writing the output.
* @param ped the {@link ProgramElementDoc} that we are documenting.
* @param holderTag the tag that holds the inheritDoc tag or null for type
* (class) docs.
* @param isFirstSentence true if we only want to inherit the first sentence.
*/
private Content retrieveInheritedDocumentation(TagletWriter writer,
ProgramElementDoc ped, Tag holderTag, boolean isFirstSentence) {
Content replacement = writer.getOutputInstance();
Configuration configuration = writer.configuration();
Taglet inheritableTaglet = holderTag == null ?
null : configuration.tagletManager.getTaglet(holderTag.name());
if (inheritableTaglet != null &&
!(inheritableTaglet instanceof InheritableTaglet)) {
String message = ped.name() +
((ped instanceof ExecutableMemberDoc)
? ((ExecutableMemberDoc)ped).flatSignature()
: "");
//This tag does not support inheritence.
configuration.message.warning(ped.position(),
"doclet.noInheritedDoc", message);
}
DocFinder.Output inheritedDoc =
DocFinder.search(new DocFinder.Input(ped,
(InheritableTaglet) inheritableTaglet, holderTag,
isFirstSentence, true));
if (inheritedDoc.isValidInheritDocTag) {
if (inheritedDoc.inlineTags.length > 0) {
replacement = writer.commentTagsToOutput(inheritedDoc.holderTag,
inheritedDoc.holder, inheritedDoc.inlineTags, isFirstSentence);
}
} else {
String message = ped.name() +
((ped instanceof ExecutableMemberDoc)
? ((ExecutableMemberDoc)ped).flatSignature()
: "");
configuration.message.warning(ped.position(),
"doclet.noInheritedDoc", message);
}
return replacement;
}
/**
* Given the <code>Tag</code> 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.
* @param tagletWriter the taglet writer for output.
* @return the Content representation of this <code>Tag</code>.
*/
public Content getTagletOutput(Tag tag, TagletWriter tagletWriter) {
if (! (tag.holder() instanceof ProgramElementDoc)) {
return tagletWriter.getOutputInstance();
}
return tag.name().equals("@inheritDoc") ?
retrieveInheritedDocumentation(tagletWriter, (ProgramElementDoc) tag.holder(), null, tagletWriter.isFirstSentence) :
retrieveInheritedDocumentation(tagletWriter, (ProgramElementDoc) tag.holder(), tag, tagletWriter.isFirstSentence);
}
}

53
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/InheritableTaglet.java Normal file
View File

@@ -0,0 +1,53 @@
/*
* Copyright (c) 2003, 2012, 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 com.sun.tools.doclets.internal.toolkit.taglets;
import com.sun.tools.doclets.internal.toolkit.util.DocFinder;
/**
* A taglet should implement this interface if it supports the inheritDoc
* tag or is automatically inherited if it is missing.
*
* <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
* @since 1.5
*/
public interface InheritableTaglet extends Taglet {
/**
* Given an {@link com.sun.tools.doclets.internal.toolkit.util.DocFinder.Output}
* object, set its values with the appropriate information to inherit
* documentation.
*
* @param input the input for documentation search.
* @param output the output for documentation search.
*/
void inherit(DocFinder.Input input, DocFinder.Output output);
}

142
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/LegacyTaglet.java Normal file
View File

@@ -0,0 +1,142 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
import com.sun.javadoc.*;
import com.sun.tools.doclets.formats.html.markup.RawHtml;
import com.sun.tools.doclets.internal.toolkit.Content;
/**
* This taglet acts as a wrapper to enable
* {@link com.sun.tools.doclets.Taglet} type taglets to work
* with the current version of Javadoc.
* Note: this taglet only works with legacy taglets (those compatible with
* Javadoc 1.4.x) that writes strings.
* This taglet is able to wrap most most legacy taglets because
* the standard doclet is the only known doclet to use legacy taglets.
*
* <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>
*
* @since 1.5
* @author Jamie Ho
*/
public class LegacyTaglet implements Taglet {
private com.sun.tools.doclets.Taglet legacyTaglet;
public LegacyTaglet(com.sun.tools.doclets.Taglet t) {
legacyTaglet = t;
}
/**
* {@inheritDoc}
*/
public boolean inField() {
return legacyTaglet.isInlineTag() || legacyTaglet.inField();
}
/**
* {@inheritDoc}
*/
public boolean inConstructor() {
return legacyTaglet.isInlineTag() || legacyTaglet.inConstructor();
}
/**
* {@inheritDoc}
*/
public boolean inMethod() {
return legacyTaglet.isInlineTag() || legacyTaglet.inMethod();
}
/**
* {@inheritDoc}
*/
public boolean inOverview() {
return legacyTaglet.isInlineTag() || legacyTaglet.inOverview();
}
/**
* {@inheritDoc}
*/
public boolean inPackage() {
return legacyTaglet.isInlineTag() || legacyTaglet.inPackage();
}
/**
* {@inheritDoc}
*/
public boolean inType() {
return legacyTaglet.isInlineTag() || legacyTaglet.inType();
}
/**
* 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 legacyTaglet.isInlineTag();
}
/**
* {@inheritDoc}
*/
public String getName() {
return legacyTaglet.getName();
}
/**
* {@inheritDoc}
*/
public Content getTagletOutput(Tag tag, TagletWriter writer)
throws IllegalArgumentException {
Content output = writer.getOutputInstance();
output.addContent(new RawHtml(legacyTaglet.toString(tag)));
return output;
}
/**
* {@inheritDoc}
*/
public Content getTagletOutput(Doc holder, TagletWriter writer)
throws IllegalArgumentException {
Content output = writer.getOutputInstance();
Tag[] tags = holder.tags(getName());
if (tags.length > 0) {
String tagString = legacyTaglet.toString(tags);
if (tagString != null) {
output.addContent(new RawHtml(tagString));
}
}
return output;
}
}

70
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/LiteralTaglet.java Normal file
View File

@@ -0,0 +1,70 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
import java.util.Map;
import com.sun.javadoc.Tag;
import com.sun.tools.doclets.internal.toolkit.Content;
/**
* An inline Taglet used to denote literal text.
* The enclosed text is interpreted as not containing HTML markup or
* nested javadoc tags.
* For example, the text:
* <blockquote> {@code {@literal a<B>c}} </blockquote>
* displays as:
* <blockquote> {@literal a<B>c} </blockquote>
*
* <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 Scott Seligman
* @since 1.5
*/
public class LiteralTaglet extends BaseInlineTaglet {
private static final String NAME = "literal";
public static void register(Map<String, Taglet> map) {
map.remove(NAME);
map.put(NAME, new LiteralTaglet());
}
public String getName() {
return NAME;
}
/**
* {@inheritDoc}
*/
public Content getTagletOutput(Tag tag, TagletWriter writer) {
return writer.literalTagOutput(tag);
}
}

324
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/ParamTaglet.java Normal file
View File

@@ -0,0 +1,324 @@
/*
* Copyright (c) 2001, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.Content;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* A taglet that represents the @param 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>
*
* @author Jamie Ho
* @since 1.4
*/
public class ParamTaglet extends BaseTaglet implements InheritableTaglet {
/**
* Construct a ParamTaglet.
*/
public ParamTaglet() {
name = "param";
}
/**
* Given an array of <code>Parameter</code>s, return
* a name/rank number map. If the array is null, then
* null is returned.
* @param params The array of parmeters (from type or executable member) to
* check.
* @return a name-rank number map.
*/
private static Map<String,String> getRankMap(Object[] params){
if (params == null) {
return null;
}
HashMap<String,String> result = new HashMap<String,String>();
for (int i = 0; i < params.length; i++) {
String name = params[i] instanceof Parameter ?
((Parameter) params[i]).name() :
((TypeVariable) params[i]).typeName();
result.put(name, String.valueOf(i));
}
return result;
}
/**
* {@inheritDoc}
*/
public void inherit(DocFinder.Input input, DocFinder.Output output) {
if (input.tagId == null) {
input.isTypeVariableParamTag = ((ParamTag) input.tag).isTypeParameter();
Object[] parameters = input.isTypeVariableParamTag ?
(Object[]) ((MethodDoc) input.tag.holder()).typeParameters() :
(Object[]) ((MethodDoc) input.tag.holder()).parameters();
String target = ((ParamTag) input.tag).parameterName();
int i;
for (i = 0; i < parameters.length; i++) {
String name = parameters[i] instanceof Parameter ?
((Parameter) parameters[i]).name() :
((TypeVariable) parameters[i]).typeName();
if (name.equals(target)) {
input.tagId = String.valueOf(i);
break;
}
}
if (i == parameters.length) {
//Someone used {@inheritDoc} on an invalid @param tag.
//We don't know where to inherit from.
//XXX: in the future when Configuration is available here,
//print a warning for this mistake.
return;
}
}
ParamTag[] tags = input.isTypeVariableParamTag ?
((MethodDoc)input.element).typeParamTags() : ((MethodDoc)input.element).paramTags();
Map<String, String> rankMap = getRankMap(input.isTypeVariableParamTag ?
(Object[]) ((MethodDoc)input.element).typeParameters() :
(Object[]) ((MethodDoc)input.element).parameters());
for (int i = 0; i < tags.length; i++) {
if (rankMap.containsKey(tags[i].parameterName()) &&
rankMap.get(tags[i].parameterName()).equals((input.tagId))) {
output.holder = input.element;
output.holderTag = tags[i];
output.inlineTags = input.isFirstSentence ?
tags[i].firstSentenceTags() : tags[i].inlineTags();
return;
}
}
}
/**
* {@inheritDoc}
*/
public boolean inField() {
return false;
}
/**
* {@inheritDoc}
*/
public boolean inMethod() {
return true;
}
/**
* {@inheritDoc}
*/
public boolean inOverview() {
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.
*/
public Content getTagletOutput(Doc holder, TagletWriter writer) {
if (holder instanceof ExecutableMemberDoc) {
ExecutableMemberDoc member = (ExecutableMemberDoc) holder;
Content output = getTagletOutput(false, member, writer,
member.typeParameters(), member.typeParamTags());
output.addContent(getTagletOutput(true, member, writer,
member.parameters(), member.paramTags()));
return output;
} else {
ClassDoc classDoc = (ClassDoc) holder;
return getTagletOutput(false, classDoc, writer,
classDoc.typeParameters(), classDoc.typeParamTags());
}
}
/**
* Given an array of <code>ParamTag</code>s,return its string representation.
* Try to inherit the param tags that are missing.
*
* @param holder the doc that holds the param tags.
* @param writer the TagletWriter that will write this tag.
* @param formalParameters The array of parmeters (from type or executable
* member) to check.
*
* @return the TagletOutput representation of these <code>ParamTag</code>s.
*/
private Content getTagletOutput(boolean isNonTypeParams, Doc holder,
TagletWriter writer, Object[] formalParameters, ParamTag[] paramTags) {
Content result = writer.getOutputInstance();
Set<String> alreadyDocumented = new HashSet<String>();
if (paramTags.length > 0) {
result.addContent(
processParamTags(isNonTypeParams, paramTags,
getRankMap(formalParameters), writer, alreadyDocumented)
);
}
if (alreadyDocumented.size() != formalParameters.length) {
//Some parameters are missing corresponding @param tags.
//Try to inherit them.
result.addContent(getInheritedTagletOutput (isNonTypeParams, holder,
writer, formalParameters, alreadyDocumented));
}
return result;
}
/**
* Loop through each indivitual parameter. It it does not have a
* corresponding param tag, try to inherit it.
*/
private Content getInheritedTagletOutput(boolean isNonTypeParams, Doc holder,
TagletWriter writer, Object[] formalParameters,
Set<String> alreadyDocumented) {
Content result = writer.getOutputInstance();
if ((! alreadyDocumented.contains(null)) &&
holder instanceof MethodDoc) {
for (int i = 0; i < formalParameters.length; i++) {
if (alreadyDocumented.contains(String.valueOf(i))) {
continue;
}
//This parameter does not have any @param documentation.
//Try to inherit it.
DocFinder.Output inheritedDoc =
DocFinder.search(new DocFinder.Input((MethodDoc) holder, this,
String.valueOf(i), ! isNonTypeParams));
if (inheritedDoc.inlineTags != null &&
inheritedDoc.inlineTags.length > 0) {
result.addContent(
processParamTag(isNonTypeParams, writer,
(ParamTag) inheritedDoc.holderTag,
isNonTypeParams ?
((Parameter) formalParameters[i]).name():
((TypeVariable) formalParameters[i]).typeName(),
alreadyDocumented.size() == 0));
}
alreadyDocumented.add(String.valueOf(i));
}
}
return result;
}
/**
* Given an array of <code>Tag</code>s representing this custom
* 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 writer the TagletWriter that will write this tag.
* @param alreadyDocumented the set of exceptions that have already
* been documented.
* @param rankMap a {@link java.util.Map} which holds ordering
* information about the parameters.
* @param rankMap a {@link java.util.Map} which holds a mapping
* 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>.
*/
private Content processParamTags(boolean isNonTypeParams,
ParamTag[] paramTags, Map<String, String> rankMap, TagletWriter writer,
Set<String> alreadyDocumented) {
Content result = writer.getOutputInstance();
if (paramTags.length > 0) {
for (int i = 0; i < paramTags.length; ++i) {
ParamTag pt = paramTags[i];
String paramName = isNonTypeParams ?
pt.parameterName() : "<" + pt.parameterName() + ">";
if (! rankMap.containsKey(pt.parameterName())) {
writer.getMsgRetriever().warning(pt.position(),
isNonTypeParams ?
"doclet.Parameters_warn" :
"doclet.Type_Parameters_warn",
paramName);
}
String rank = rankMap.get(pt.parameterName());
if (rank != null && alreadyDocumented.contains(rank)) {
writer.getMsgRetriever().warning(pt.position(),
isNonTypeParams ?
"doclet.Parameters_dup_warn" :
"doclet.Type_Parameters_dup_warn",
paramName);
}
result.addContent(processParamTag(isNonTypeParams, writer, pt,
pt.parameterName(), alreadyDocumented.size() == 0));
alreadyDocumented.add(rank);
}
}
return result;
}
/**
* Convert the individual ParamTag into Content.
*
* @param isNonTypeParams true if this is just a regular param tag. False
* if this is a type param tag.
* @param writer the taglet writer for output writing.
* @param paramTag the tag whose inline tags will be printed.
* @param name the name of the parameter. We can't rely on
* the name in the param tag because we might be
* inheriting documentation.
* @param isFirstParam true if this is the first param tag being printed.
*
*/
private Content processParamTag(boolean isNonTypeParams,
TagletWriter writer, ParamTag paramTag, String name,
boolean isFirstParam) {
Content result = writer.getOutputInstance();
String header = writer.configuration().getText(
isNonTypeParams ? "doclet.Parameters" : "doclet.TypeParameters");
if (isFirstParam) {
result.addContent(writer.getParamHeader(header));
}
result.addContent(writer.paramTagOutput(paramTag,
name));
return result;
}
}

50
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/PropertyGetterTaglet.java Normal file
View File

@@ -0,0 +1,50 @@
/*
* Copyright (c) 2001, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
/**
* A taglet that adds the initial line of documentation to the JavaFX
* property getters.
*
* <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 PropertyGetterTaglet extends BasePropertyTaglet {
/**
* Construct a new PropertyGetterTaglet.
*/
public PropertyGetterTaglet () {
name = "propertyGetter";
}
@Override
String getText(TagletWriter tagletWriter) {
return tagletWriter.configuration().getText("doclet.PropertyGetter");
}
}

50
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/PropertySetterTaglet.java Normal file
View File

@@ -0,0 +1,50 @@
/*
* Copyright (c) 2001, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
/**
* A taglet that adds the initial line of documentation to the JavaFX
* property setters.
*
* <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 PropertySetterTaglet extends BasePropertyTaglet {
/**
* Construct a new PropertyGetterTaglet.
*/
public PropertySetterTaglet () {
name = "propertySetter";
}
@Override
String getText(TagletWriter tagletWriter) {
return tagletWriter.configuration().getText("doclet.PropertySetter");
}
}

97
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/ReturnTaglet.java Normal file
View File

@@ -0,0 +1,97 @@
/*
* Copyright (c) 2001, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.Content;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* A taglet that represents the @return 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>
*
* @author Jamie Ho
* @since 1.4
*/
public class ReturnTaglet extends BaseExecutableMemberTaglet
implements InheritableTaglet {
public ReturnTaglet() {
name = "return";
}
/**
* {@inheritDoc}
*/
public void inherit(DocFinder.Input input, DocFinder.Output output) {
Tag[] tags = input.element.tags("return");
if (tags.length > 0) {
output.holder = input.element;
output.holderTag = tags[0];
output.inlineTags = input.isFirstSentence ?
tags[0].firstSentenceTags() : tags[0].inlineTags();
}
}
/**
* 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}
*/
public Content getTagletOutput(Doc holder, TagletWriter writer) {
Type returnType = ((MethodDoc) holder).returnType();
Tag[] tags = holder.tags(name);
//Make sure we are not using @return tag on method with void return type.
if (returnType.isPrimitive() && returnType.typeName().equals("void")) {
if (tags.length > 0) {
writer.getMsgRetriever().warning(holder.position(),
"doclet.Return_tag_on_void_method");
}
return null;
}
//Inherit @return tag if necessary.
if (tags.length == 0) {
DocFinder.Output inheritedDoc =
DocFinder.search(new DocFinder.Input((MethodDoc) holder, this));
tags = inheritedDoc.holderTag == null ? tags : new Tag[] {inheritedDoc.holderTag};
}
return tags.length > 0 ? writer.returnTagOutput(tags[0]) : null;
}
}

76
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/SeeTaglet.java Normal file
View File

@@ -0,0 +1,76 @@
/*
* Copyright (c) 2001, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.Content;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* A taglet that represents the @see 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>
*
* @author Jamie Ho
* @since 1.4
*/
public class SeeTaglet extends BaseTaglet implements InheritableTaglet {
public SeeTaglet() {
name = "see";
}
/**
* {@inheritDoc}
*/
public void inherit(DocFinder.Input input, DocFinder.Output output) {
Tag[] tags = input.element.seeTags();
if (tags.length > 0) {
output.holder = input.element;
output.holderTag = tags[0];
output.inlineTags = input.isFirstSentence ?
tags[0].firstSentenceTags() : tags[0].inlineTags();
}
}
/**
* {@inheritDoc}
*/
public Content getTagletOutput(Doc holder, TagletWriter writer) {
SeeTag[] tags = holder.seeTags();
if (tags.length == 0 && holder instanceof MethodDoc) {
DocFinder.Output inheritedDoc =
DocFinder.search(new DocFinder.Input((MethodDoc) holder, this));
if (inheritedDoc.holder != null) {
tags = inheritedDoc.holder.seeTags();
}
}
return writer.seeTagOutput(holder, tags);
}
}

232
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/SimpleTaglet.java Normal file
View File

@@ -0,0 +1,232 @@
/*
* Copyright (c) 2001, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.Content;
import com.sun.tools.doclets.internal.toolkit.util.DocFinder;
import com.sun.tools.javac.util.StringUtils;
/**
* A simple single argument custom 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>
*
* @author Jamie Ho
*/
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 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.
*/
protected String locations;
/**
* Construct a <code>SimpleTaglet</code>.
* @param tagName the name of this tag
* @param header the header to output.
* @param locations the possible 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, String locations) {
this.tagName = tagName;
this.header = header;
locations = StringUtils.toLowerCase(locations);
if (locations.indexOf(ALL) != -1 && locations.indexOf(EXCLUDED) == -1) {
this.locations = PACKAGE + TYPE + FIELD + METHOD + CONSTRUCTOR + OVERVIEW;
} else {
this.locations = locations;
}
}
/**
* 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.indexOf(CONSTRUCTOR) != -1 && locations.indexOf(EXCLUDED) == -1;
}
/**
* 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.indexOf(FIELD) != -1 && locations.indexOf(EXCLUDED) == -1;
}
/**
* 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.indexOf(METHOD) != -1 && locations.indexOf(EXCLUDED) == -1;
}
/**
* 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.indexOf(OVERVIEW) != -1 && locations.indexOf(EXCLUDED) == -1;
}
/**
* 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.indexOf(PACKAGE) != -1 && locations.indexOf(EXCLUDED) == -1;
}
/**
* 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.indexOf(TYPE) != -1&& locations.indexOf(EXCLUDED) == -1;
}
/**
* 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;
}
@Override
public void inherit(DocFinder.Input input, DocFinder.Output output) {
Tag[] tags = input.element.tags(tagName);
if (tags.length > 0) {
output.holder = input.element;
output.holderTag = tags[0];
output.inlineTags = input.isFirstSentence
? tags[0].firstSentenceTags() : tags[0].inlineTags();
}
}
/**
* {@inheritDoc}
*/
public Content getTagletOutput(Tag tag, TagletWriter writer) {
return header == null || tag == null ? null : writer.simpleTagOutput(tag, header);
}
/**
* {@inheritDoc}
*/
public Content getTagletOutput(Doc holder, TagletWriter writer) {
if (header == null || holder.tags(getName()).length == 0) {
return null;
}
return writer.simpleTagOutput(holder.tags(getName()), header);
}
}

158
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/Taglet.java Normal file
View File

@@ -0,0 +1,158 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.Content;
/**
* The interface for a custom tag used by Doclets. A custom
* tag must implement this interface. To be loaded and used by
* doclets at run-time, the taglet must have a static method called
* <code>register</code> that accepts a {@link java.util.Map} as an
* argument with the following signature:
* <pre>
* public void register(Map map)
* </pre>
* This method should add an instance of the custom taglet to the map
* with the name of the taglet as the key. If overriding a taglet,
* to avoid a name conflict, the overridden taglet must be deleted from
* the map before an instance of the new taglet is added to the map.
* <p>
* It is recommended that the taglet throw an exception when it fails
* to register itself. The exception that it throws is up to the user.
* <p>
* Here are two sample taglets: <br>
* <ul>
* <li><a href="{@docRoot}/ToDoTaglet.java">ToDoTaglet.java</a>
* - Standalone taglet</li>
* <li><a href="{@docRoot}/UnderlineTaglet.java">UnderlineTaglet.java</a>
* - Inline taglet</li>
* </ul>
* <p>
* For more information on how to create your own Taglets, please see the
* <a href="{@docRoot}/overview.html">Taglet Overview</a>.
*
* @since 1.4
* @author Jamie Ho
*/
public interface Taglet {
/**
* 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 abstract boolean inField();
/**
* 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 abstract boolean inConstructor();
/**
* 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
* otherwise.
*/
public abstract boolean inMethod();
/**
* 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
* otherwise.
*/
public abstract boolean inOverview();
/**
* 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 abstract boolean inPackage();
/**
* 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 abstract boolean inType();
/**
* Return true if this <code>Taglet</code>
* is an inline tag. Return false otherwise.
* @return true if this <code>Taglet</code>
* is an inline tag and false otherwise.
*/
public abstract boolean isInlineTag();
/**
* Return the name of this custom tag.
* @return the name of this custom tag.
*/
public abstract String getName();
/**
* Given the <code>Tag</code> representation of this custom
* tag, return its Content representation, which is output
* to the generated page.
* @param tag the <code>Tag</code> representation of this custom tag.
* @param writer a {@link TagletWriter} Taglet writer.
* @throws IllegalArgumentException thrown when the method is not supported by the taglet.
* @return the Content representation of this <code>Tag</code>.
*/
public abstract Content getTagletOutput(Tag tag, TagletWriter writer) throws IllegalArgumentException;
/**
* 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 a {@link Doc} object holding the custom tag.
* @param writer a {@link TagletWriter} Taglet writer.
* @throws IllegalArgumentException thrown when the method is not supported by the taglet.
* @return the TagletOutput representation of this <code>Tag</code>.
*/
public abstract Content getTagletOutput(Doc holder, TagletWriter writer) throws IllegalArgumentException;
@Override
public abstract String toString();
}

761
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/TagletManager.java Normal file
View File

@@ -0,0 +1,761 @@
/*
* Copyright (c) 2001, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
import java.io.*;
import java.lang.reflect.*;
import java.net.*;
import java.util.*;
import javax.tools.DocumentationTool;
import javax.tools.JavaFileManager;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
import com.sun.tools.javac.util.StringUtils;
/**
* Manages the<code>Taglet</code>s used by doclets.
*
* <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
* @since 1.4
*/
public class TagletManager {
/**
* The default separator for the simple tag option.
*/
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.
*/
public static final String ALT_SIMPLE_TAGLET_OPT_SEPARATOR = "-";
/**
* The map of custom tags.
*/
private LinkedHashMap<String,Taglet> customTags;
/**
* The array of custom tags that can appear in packages.
*/
private Taglet[] packageTags;
/**
* The array of custom tags that can appear in classes or interfaces.
*/
private Taglet[] typeTags;
/**
* The array of custom tags that can appear in fields.
*/
private Taglet[] fieldTags;
/**
* The array of custom tags that can appear in constructors.
*/
private Taglet[] constructorTags;
/**
* The array of custom tags that can appear in methods.
*/
private Taglet[] methodTags;
/**
* The array of custom tags that can appear in the overview.
*/
private Taglet[] overviewTags;
/**
* The array of custom tags that can appear in comments.
*/
private Taglet[] inlineTags;
/**
* The array of custom tags that can appear in the serialized form.
*/
private Taglet[] serializedFormTags;
/**
* The message retriever that will be used to print error messages.
*/
private MessageRetriever message;
/**
* Keep track of standard tags.
*/
private Set<String> standardTags;
/**
* Keep track of standard tags in lowercase to compare for better
* error messages when a tag like @docRoot is mistakenly spelled
* lowercase @docroot.
*/
private Set<String> standardTagsLowercase;
/**
* Keep track of overriden standard tags.
*/
private Set<String> overridenStandardTags;
/**
* Keep track of the tags that may conflict
* with standard tags in the future (any custom tag without
* a period in its name).
*/
private Set<String> potentiallyConflictingTags;
/**
* The set of unseen custom tags.
*/
private Set<String> unseenCustomTags;
/**
* True if we do not want to use @since tags.
*/
private boolean nosince;
/**
* True if we want to use @version tags.
*/
private boolean showversion;
/**
* True if we want to use @author tags.
*/
private boolean showauthor;
/**
* True if we want to use JavaFX-related tags (@propertyGetter,
* @propertySetter, @propertyDescription, @defaultValue, @treatAsPrivate).
*/
private boolean javafx;
/**
* Construct a new <code>TagletManager</code>.
* @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.
* @param message the message retriever to print warnings.
*/
public TagletManager(boolean nosince, boolean showversion,
boolean showauthor, boolean javafx,
MessageRetriever message) {
overridenStandardTags = new HashSet<String>();
potentiallyConflictingTags = new HashSet<String>();
standardTags = new HashSet<String>();
standardTagsLowercase = new HashSet<String>();
unseenCustomTags = new HashSet<String>();
customTags = new LinkedHashMap<String,Taglet>();
this.nosince = nosince;
this.showversion = showversion;
this.showauthor = showauthor;
this.javafx = javafx;
this.message = message;
initStandardTaglets();
initStandardTagsLowercase();
}
/**
* Add a new <code>CustomTag</code>. 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.
*/
public void addCustomTag(Taglet customTag) {
if (customTag != null) {
String name = customTag.getName();
if (customTags.containsKey(name)) {
customTags.remove(name);
}
customTags.put(name, customTag);
checkTagName(name);
}
}
public Set<String> getCustomTagNames() {
return customTags.keySet();
}
/**
* Add a new <code>Taglet</code>. 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 tagletPath the path to the class representing the custom tag.
*/
public void addCustomTag(String classname, JavaFileManager fileManager, String tagletPath) {
try {
Class<?> customTagClass = null;
// construct class loader
String cpString = null; // make sure env.class.path defaults to dot
ClassLoader tagClassLoader;
if (fileManager != null && fileManager.hasLocation(DocumentationTool.Location.TAGLET_PATH)) {
tagClassLoader = fileManager.getClassLoader(DocumentationTool.Location.TAGLET_PATH);
} else {
// do prepends to get correct ordering
cpString = appendPath(System.getProperty("env.class.path"), cpString);
cpString = appendPath(System.getProperty("java.class.path"), cpString);
cpString = appendPath(tagletPath, cpString);
tagClassLoader = new URLClassLoader(pathToURLs(cpString));
}
customTagClass = tagClassLoader.loadClass(classname);
Method meth = customTagClass.getMethod("register",
new Class<?>[] {java.util.Map.class});
Object[] list = customTags.values().toArray();
Taglet lastTag = (list != null && list.length > 0)
? (Taglet) list[list.length-1] : null;
meth.invoke(null, new Object[] {customTags});
list = customTags.values().toArray();
Object newLastTag = (list != null&& list.length > 0)
? list[list.length-1] : null;
if (lastTag != newLastTag) {
//New taglets must always be added to the end of the LinkedHashMap.
//If the current and previous last taglet are not equal, that
//means a new Taglet has been added.
message.notice("doclet.Notice_taglet_registered", classname);
if (newLastTag != null) {
checkTaglet(newLastTag);
}
}
} catch (Exception exc) {
message.error("doclet.Error_taglet_not_registered", exc.getClass().getName(), classname);
}
}
private String appendPath(String path1, String path2) {
if (path1 == null || path1.length() == 0) {
return path2 == null ? "." : path2;
} else if (path2 == null || path2.length() == 0) {
return path1;
} else {
return path1 + File.pathSeparator + path2;
}
}
/**
* Utility method for converting a search path string to an array
* of directory and JAR file URLs.
*
* @param path the search path string
* @return the resulting array of directory and JAR file URLs
*/
private URL[] pathToURLs(String path) {
Set<URL> urls = new LinkedHashSet<URL>();
for (String s: path.split(File.pathSeparator)) {
if (s.isEmpty()) continue;
try {
urls.add(new File(s).getAbsoluteFile().toURI().toURL());
} catch (MalformedURLException e) {
message.error("doclet.MalformedURL", s);
}
}
return urls.toArray(new URL[urls.size()]);
}
/**
* Add a new <code>SimpleTaglet</code>. 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
* SimpleTaglet to list.
* @param tagName the name of this tag
* @param header the header to output.
* @param locations the possible locations that this tag
* can appear in.
*/
public void addNewSimpleCustomTag(String tagName, String header, String locations) {
if (tagName == null || locations == null) {
return;
}
Taglet tag = customTags.get(tagName);
locations = StringUtils.toLowerCase(locations);
if (tag == null || header != null) {
customTags.remove(tagName);
customTags.put(tagName, new SimpleTaglet(tagName, header, locations));
if (locations != null && locations.indexOf('x') == -1) {
checkTagName(tagName);
}
} else {
//Move to back
customTags.remove(tagName);
customTags.put(tagName, tag);
}
}
/**
* Given a tag name, add it to the set of tags it belongs to.
*/
private void checkTagName(String name) {
if (standardTags.contains(name)) {
overridenStandardTags.add(name);
} else {
if (name.indexOf('.') == -1) {
potentiallyConflictingTags.add(name);
}
unseenCustomTags.add(name);
}
}
/**
* 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 com.sun.tools.doclets.Taglet) {
com.sun.tools.doclets.Taglet legacyTaglet = (com.sun.tools.doclets.Taglet) taglet;
customTags.remove(legacyTaglet.getName());
customTags.put(legacyTaglet.getName(), new LegacyTaglet(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) {
unseenCustomTags.remove(name);
}
/**
* Given an array of <code>Tag</code>s, check for spelling mistakes.
* @param doc the Doc object that holds the tags.
* @param tags the list of <code>Tag</code>s to check.
* @param areInlineTags true if the array of tags are inline and false otherwise.
*/
public void checkTags(Doc doc, Tag[] tags, boolean areInlineTags) {
if (tags == null) {
return;
}
Taglet taglet;
for (int i = 0; i < tags.length; i++) {
String name = tags[i].name();
if (name.length() > 0 && name.charAt(0) == '@') {
name = name.substring(1, name.length());
}
if (! (standardTags.contains(name) || customTags.containsKey(name))) {
if (standardTagsLowercase.contains(StringUtils.toLowerCase(name))) {
message.warning(tags[i].position(), "doclet.UnknownTagLowercase", tags[i].name());
continue;
} else {
message.warning(tags[i].position(), "doclet.UnknownTag", tags[i].name());
continue;
}
}
//Check if this tag is being used in the wrong location.
if ((taglet = customTags.get(name)) != null) {
if (areInlineTags && ! taglet.isInlineTag()) {
printTagMisuseWarn(taglet, tags[i], "inline");
}
if ((doc instanceof RootDoc) && ! taglet.inOverview()) {
printTagMisuseWarn(taglet, tags[i], "overview");
} else if ((doc instanceof PackageDoc) && ! taglet.inPackage()) {
printTagMisuseWarn(taglet, tags[i], "package");
} else if ((doc instanceof ClassDoc) && ! taglet.inType()) {
printTagMisuseWarn(taglet, tags[i], "class");
} else if ((doc instanceof ConstructorDoc) && ! taglet.inConstructor()) {
printTagMisuseWarn(taglet, tags[i], "constructor");
} else if ((doc instanceof FieldDoc) && ! taglet.inField()) {
printTagMisuseWarn(taglet, tags[i], "field");
} else if ((doc instanceof MethodDoc) && ! taglet.inMethod()) {
printTagMisuseWarn(taglet, tags[i], "method");
}
}
}
}
/**
* Given the taglet, the tag and the type of documentation that the tag
* was found in, print a tag misuse warning.
* @param taglet the taglet representing the misused tag.
* @param tag the misused tag.
* @param holderType the type of documentation that the misused tag was found in.
*/
private void printTagMisuseWarn(Taglet taglet, Tag tag, String holderType) {
Set<String> locationsSet = new LinkedHashSet<String>();
if (taglet.inOverview()) {
locationsSet.add("overview");
}
if (taglet.inPackage()) {
locationsSet.add("package");
}
if (taglet.inType()) {
locationsSet.add("class/interface");
}
if (taglet.inConstructor()) {
locationsSet.add("constructor");
}
if (taglet.inField()) {
locationsSet.add("field");
}
if (taglet.inMethod()) {
locationsSet.add("method");
}
if (taglet.isInlineTag()) {
locationsSet.add("inline text");
}
String[] locations = locationsSet.toArray(new String[]{});
if (locations == null || locations.length == 0) {
//This known tag is excluded.
return;
}
StringBuilder combined_locations = new StringBuilder();
for (int i = 0; i < locations.length; i++) {
if (i > 0) {
combined_locations.append(", ");
}
combined_locations.append(locations[i]);
}
message.warning(tag.position(), "doclet.tag_misuse",
"@" + taglet.getName(), holderType, combined_locations.toString());
}
/**
* 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 Taglet[] getPackageCustomTaglets() {
if (packageTags == null) {
initCustomTagletArrays();
}
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 Taglet[] getTypeCustomTaglets() {
if (typeTags == null) {
initCustomTagletArrays();
}
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 Taglet[] getInlineCustomTaglets() {
if (inlineTags == null) {
initCustomTagletArrays();
}
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 Taglet[] getFieldCustomTaglets() {
if (fieldTags == null) {
initCustomTagletArrays();
}
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.
*/
public Taglet[] getSerializedFormTaglets() {
if (serializedFormTags == null) {
initCustomTagletArrays();
}
return serializedFormTags;
}
/**
* @return the array of <code>Taglet</code>s that can
* appear in the given Doc.
*/
public Taglet[] getCustomTaglets(Doc doc) {
if (doc instanceof ConstructorDoc) {
return getConstructorCustomTaglets();
} else if (doc instanceof MethodDoc) {
return getMethodCustomTaglets();
} else if (doc instanceof FieldDoc) {
return getFieldCustomTaglets();
} else if (doc instanceof ClassDoc) {
return getTypeCustomTaglets();
} else if (doc instanceof PackageDoc) {
return getPackageCustomTaglets();
} else if (doc instanceof RootDoc) {
return getOverviewCustomTaglets();
}
return null;
}
/**
* Return the array of <code>Taglet</code>s that can
* appear in constructors.
* @return the array of <code>Taglet</code>s that can
* appear in constructors.
*/
public Taglet[] getConstructorCustomTaglets() {
if (constructorTags == null) {
initCustomTagletArrays();
}
return constructorTags;
}
/**
* Return the array of <code>Taglet</code>s that can
* appear in methods.
* @return the array of <code>Taglet</code>s that can
* appear in methods.
*/
public Taglet[] getMethodCustomTaglets() {
if (methodTags == null) {
initCustomTagletArrays();
}
return methodTags;
}
/**
* Return the array 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 Taglet[] getOverviewCustomTaglets() {
if (overviewTags == null) {
initCustomTagletArrays();
}
return overviewTags;
}
/**
* Initialize the custom tag arrays.
*/
private void initCustomTagletArrays() {
Iterator<Taglet> it = customTags.values().iterator();
ArrayList<Taglet> pTags = new ArrayList<Taglet>(customTags.size());
ArrayList<Taglet> tTags = new ArrayList<Taglet>(customTags.size());
ArrayList<Taglet> fTags = new ArrayList<Taglet>(customTags.size());
ArrayList<Taglet> cTags = new ArrayList<Taglet>(customTags.size());
ArrayList<Taglet> mTags = new ArrayList<Taglet>(customTags.size());
ArrayList<Taglet> iTags = new ArrayList<Taglet>(customTags.size());
ArrayList<Taglet> oTags = new ArrayList<Taglet>(customTags.size());
ArrayList<Taglet> sTags = new ArrayList<Taglet>();
Taglet current;
while (it.hasNext()) {
current = it.next();
if (current.inPackage() && !current.isInlineTag()) {
pTags.add(current);
}
if (current.inType() && !current.isInlineTag()) {
tTags.add(current);
}
if (current.inField() && !current.isInlineTag()) {
fTags.add(current);
}
if (current.inConstructor() && !current.isInlineTag()) {
cTags.add(current);
}
if (current.inMethod() && !current.isInlineTag()) {
mTags.add(current);
}
if (current.isInlineTag()) {
iTags.add(current);
}
if (current.inOverview() && !current.isInlineTag()) {
oTags.add(current);
}
}
packageTags = pTags.toArray(new Taglet[] {});
typeTags = tTags.toArray(new Taglet[] {});
fieldTags = fTags.toArray(new Taglet[] {});
constructorTags = cTags.toArray(new Taglet[] {});
methodTags = mTags.toArray(new Taglet[] {});
overviewTags = oTags.toArray(new Taglet[] {});
inlineTags = iTags.toArray(new Taglet[] {});
//Init the serialized form tags
sTags.add(customTags.get("serialData"));
sTags.add(customTags.get("throws"));
if (!nosince)
sTags.add(customTags.get("since"));
sTags.add(customTags.get("see"));
serializedFormTags = sTags.toArray(new Taglet[] {});
}
/**
* Initialize standard Javadoc tags for ordering purposes.
*/
private void initStandardTaglets() {
if (javafx) {
initJavaFXTaglets();
}
Taglet temp;
addStandardTaglet(new ParamTaglet());
addStandardTaglet(new ReturnTaglet());
addStandardTaglet(new ThrowsTaglet());
addStandardTaglet(new SimpleTaglet("exception", null,
SimpleTaglet.METHOD + SimpleTaglet.CONSTRUCTOR));
addStandardTaglet(!nosince, new SimpleTaglet("since", message.getText("doclet.Since"),
SimpleTaglet.ALL));
addStandardTaglet(showversion, new SimpleTaglet("version", message.getText("doclet.Version"),
SimpleTaglet.PACKAGE + SimpleTaglet.TYPE + SimpleTaglet.OVERVIEW));
addStandardTaglet(showauthor, new SimpleTaglet("author", message.getText("doclet.Author"),
SimpleTaglet.PACKAGE + SimpleTaglet.TYPE + SimpleTaglet.OVERVIEW));
addStandardTaglet(new SimpleTaglet("serialData", message.getText("doclet.SerialData"),
SimpleTaglet.EXCLUDED));
customTags.put((temp = new SimpleTaglet("factory", message.getText("doclet.Factory"),
SimpleTaglet.METHOD)).getName(), temp);
addStandardTaglet(new SeeTaglet());
//Standard inline tags
addStandardTaglet(new DocRootTaglet());
addStandardTaglet(new InheritDocTaglet());
addStandardTaglet(new ValueTaglet());
addStandardTaglet(new LiteralTaglet());
addStandardTaglet(new CodeTaglet());
// Keep track of the names of standard tags for error
// checking purposes. The following are not handled above.
// See, for example, com.sun.tools.javadoc.Comment
standardTags.add("deprecated");
standardTags.add("link");
standardTags.add("linkplain");
standardTags.add("serial");
standardTags.add("serialField");
standardTags.add("Text");
}
/**
* Initialize JavaFX-related tags.
*/
private void initJavaFXTaglets() {
addStandardTaglet(new PropertyGetterTaglet());
addStandardTaglet(new PropertySetterTaglet());
addStandardTaglet(new SimpleTaglet("propertyDescription",
message.getText("doclet.PropertyDescription"),
SimpleTaglet.FIELD + SimpleTaglet.METHOD));
addStandardTaglet(new SimpleTaglet("defaultValue", message.getText("doclet.DefaultValue"),
SimpleTaglet.FIELD + SimpleTaglet.METHOD));
addStandardTaglet(new SimpleTaglet("treatAsPrivate", null,
SimpleTaglet.FIELD + SimpleTaglet.METHOD + SimpleTaglet.TYPE));
}
void addStandardTaglet(Taglet taglet) {
String name = taglet.getName();
customTags.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() {
Iterator<String> it = standardTags.iterator();
while (it.hasNext()) {
standardTagsLowercase.add(StringUtils.toLowerCase(it.next()));
}
}
public boolean isKnownCustomTag(String tagName) {
return customTags.containsKey(tagName);
}
/**
* Print a list of {@link Taglet}s that might conflict with
* standard tags in the future and a list of standard tags
* that have been overriden.
*/
public void printReport() {
printReportHelper("doclet.Notice_taglet_conflict_warn", potentiallyConflictingTags);
printReportHelper("doclet.Notice_taglet_overriden", overridenStandardTags);
printReportHelper("doclet.Notice_taglet_unseen", unseenCustomTags);
}
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 += ", ";
}
}
message.notice(noticeKey, result);
}
}
/**
* Given the name of a tag, return the corresponding taglet.
* Return null if the tag is unknown.
*
* @param name the name of the taglet to retrieve.
* @return return the corresponding taglet. Return null if the tag is
* unknown.
*/
public Taglet getTaglet(String name) {
if (name.indexOf("@") == 0) {
return customTags.get(name.substring(1));
} else {
return customTags.get(name);
}
}
}

310
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/TagletWriter.java Normal file
View File

@@ -0,0 +1,310 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* The interface for the taglet writer.
*
* <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>
*
* @since 1.5
* @author Jamie Ho
*/
public abstract class TagletWriter {
/**
* True if we only want to write the first sentence.
*/
protected final boolean isFirstSentence;
protected TagletWriter(boolean isFirstSentence) {
this.isFirstSentence = isFirstSentence;
}
/**
* @return an instance of an output object.
*/
public abstract Content getOutputInstance();
/**
* Return the output for a {@code...} tag.
*
* @param tag the tag.
* @return the output of the taglet.
*/
protected abstract Content codeTagOutput(Tag tag);
/**
* Returns the output for the DocRoot inline tag.
* @return the output for the DocRoot inline tag.
*/
protected abstract Content getDocRootOutput();
/**
* Return the deprecated tag output.
*
* @param doc the doc to write deprecated documentation for.
* @return the output of the deprecated tag.
*/
protected abstract Content deprecatedTagOutput(Doc doc);
/**
* Return the output for a {@literal...} tag.
*
* @param tag the tag.
* @return the output of the taglet.
*/
protected abstract Content literalTagOutput(Tag tag);
/**
* Returns {@link MessageRetriever} for output purposes.
*
* @return {@link MessageRetriever} for output purposes.
*/
protected abstract MessageRetriever getMsgRetriever();
/**
* Return the header for the param tags.
*
* @param header the header to display.
* @return the header for the param tags.
*/
protected abstract Content getParamHeader(String header);
/**
* Return the output for param tags.
*
* @param paramTag the parameter to document.
* @param paramName the name of the parameter.
* @return the output of the param tag.
*/
protected abstract Content paramTagOutput(ParamTag paramTag,
String paramName);
/**
* Return the output for property tags.
*
* @param propertyTag the parameter to document.
* @param prefix the text with which to prefix the property name.
* @return the output of the param tag.
*/
protected abstract Content propertyTagOutput(Tag propertyTag, String prefix);
/**
* Return the return tag output.
*
* @param returnTag the return tag to output.
* @return the output of the return tag.
*/
protected abstract Content returnTagOutput(Tag returnTag);
/**
* Return the see tag output.
*
* @param seeTags the array of See tags.
* @return the output of the see tags.
*/
protected abstract Content seeTagOutput(Doc holder, SeeTag[] seeTags);
/**
* Return the output for a simple tag.
*
* @param simpleTags the array of simple tags.
* @return the output of the simple tags.
*/
protected abstract Content simpleTagOutput(Tag[] simpleTags,
String header);
/**
* Return the output for a simple tag.
*
* @param simpleTag the simple tag.
* @return the output of the simple tag.
*/
protected abstract Content simpleTagOutput(Tag simpleTag, String header);
/**
* Return the header for the throws tag.
*
* @return the header for the throws tag.
*/
protected abstract Content getThrowsHeader();
/**
* Return the header for the throws tag.
*
* @param throwsTag the throws tag.
* @return the output of the throws tag.
*/
protected abstract Content throwsTagOutput(ThrowsTag throwsTag);
/**
* Return the output for the throws tag.
*
* @param throwsType the throws type.
* @return the output of the throws type.
*/
protected abstract Content throwsTagOutput(Type throwsType);
/**
* Return the output for the value tag.
*
* @param field the constant field that holds the value tag.
* @param constantVal the constant value to document.
* @param includeLink true if we should link the constant text to the
* constant field itself.
* @return the output of the value tag.
*/
protected abstract Content valueTagOutput(FieldDoc field,
String constantVal, boolean includeLink);
/**
* Given an output object, append to it the tag documentation for
* the given member.
*
* @param tagletManager the manager that manages the taglets.
* @param doc the Doc that we are print tags for.
* @param taglets the taglets to print.
* @param writer the writer that will generate the output strings.
* @param output the output buffer to store the output in.
*/
public static void genTagOuput(TagletManager tagletManager, Doc doc,
Taglet[] taglets, TagletWriter writer, Content output) {
tagletManager.checkTags(doc, doc.tags(), false);
tagletManager.checkTags(doc, doc.inlineTags(), true);
Content currentOutput = null;
for (int i = 0; i < taglets.length; i++) {
currentOutput = null;
if (doc instanceof ClassDoc && taglets[i] instanceof ParamTaglet) {
//The type parameters are documented in a special section away
//from the tag info, so skip here.
continue;
}
if (taglets[i] instanceof DeprecatedTaglet) {
//Deprecated information is documented "inline", not in tag info
//section.
continue;
}
try {
currentOutput = taglets[i].getTagletOutput(doc, writer);
} catch (IllegalArgumentException e) {
//The taglet does not take a member as an argument. Let's try
//a single tag.
Tag[] tags = doc.tags(taglets[i].getName());
if (tags.length > 0) {
currentOutput = taglets[i].getTagletOutput(tags[0], writer);
}
}
if (currentOutput != null) {
tagletManager.seenCustomTag(taglets[i].getName());
output.addContent(currentOutput);
}
}
}
/**
* Given an inline tag, return its output.
* @param tagletManager The taglet manager for the current doclet.
* @param holderTag The tag this holds this inline tag. Null if there
* is no tag that holds it.
* @param inlineTag The inline tag to be documented.
* @param tagletWriter The taglet writer to write the output.
* @return The output of the inline tag.
*/
public static Content getInlineTagOuput(TagletManager tagletManager,
Tag holderTag, Tag inlineTag, TagletWriter tagletWriter) {
Taglet[] definedTags = tagletManager.getInlineCustomTaglets();
//This is a custom inline tag.
for (int j = 0; j < definedTags.length; j++) {
if (("@"+definedTags[j].getName()).equals(inlineTag.name())) {
//Given a name of a seen custom tag, remove it from the
// set of unseen custom tags.
tagletManager.seenCustomTag(definedTags[j].getName());
Content output = definedTags[j].getTagletOutput(
holderTag != null &&
definedTags[j].getName().equals("inheritDoc") ?
holderTag : inlineTag, tagletWriter);
return output;
}
}
return null;
}
/**
* Converts inline tags and text to TagOutput, expanding the
* inline tags along the way. Called wherever text can contain
* an inline tag, such as in comments or in free-form text arguments
* to non-inline tags.
*
* @param holderTag the tag that holds the documentation.
* @param tags array of text tags and inline tags (often alternating)
* present in the text of interest for this doc.
* @return the {@link Content} representing the comments.
*/
public abstract Content commentTagsToOutput(Tag holderTag, Tag[] tags);
/**
* Converts inline tags and text to TagOutput, expanding the
* inline tags along the way. Called wherever text can contain
* an inline tag, such as in comments or in free-form text arguments
* to non-inline tags.
*
* @param holderDoc specific doc where comment resides.
* @param tags array of text tags and inline tags (often alternating)
* present in the text of interest for this doc.
* @return the {@link Content} representing the comments.
*/
public abstract Content commentTagsToOutput(Doc holderDoc, Tag[] tags);
/**
* Converts inline tags and text to TagOutput, expanding the
* inline tags along the way. Called wherever text can contain
* an inline tag, such as in comments or in free-form text arguments
* to non-inline tags.
*
* @param holderTag the tag that holds the documentation.
* @param holderDoc specific doc where comment resides.
* @param tags array of text tags and inline tags (often alternating)
* present in the text of interest for this doc.
* @param isFirstSentence true if this is the first sentence.
* @return the {@link Content} representing the comments.
*/
public abstract Content commentTagsToOutput(Tag holderTag,
Doc holderDoc, Tag[] tags, boolean isFirstSentence);
/**
* @return an instance of the configuration used for this doclet.
*/
public abstract Configuration configuration();
}

187
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/ThrowsTaglet.java Normal file
View File

@@ -0,0 +1,187 @@
/*
* Copyright (c) 2001, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.Content;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* A taglet that represents the @throws 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>
*
* @author Jamie Ho
* @since 1.4
*/
public class ThrowsTaglet extends BaseExecutableMemberTaglet
implements InheritableTaglet {
public ThrowsTaglet() {
name = "throws";
}
/**
* {@inheritDoc}
*/
public void inherit(DocFinder.Input input, DocFinder.Output output) {
ClassDoc exception;
if (input.tagId == null) {
ThrowsTag throwsTag = (ThrowsTag) input.tag;
exception = throwsTag.exception();
input.tagId = exception == null ?
throwsTag.exceptionName() :
throwsTag.exception().qualifiedName();
} else {
exception = input.element.containingClass().findClass(input.tagId);
}
ThrowsTag[] tags = ((MethodDoc)input.element).throwsTags();
for (int i = 0; i < tags.length; i++) {
if (input.tagId.equals(tags[i].exceptionName()) ||
(tags[i].exception() != null &&
(input.tagId.equals(tags[i].exception().qualifiedName())))) {
output.holder = input.element;
output.holderTag = tags[i];
output.inlineTags = input.isFirstSentence ?
tags[i].firstSentenceTags() : tags[i].inlineTags();
output.tagList.add(tags[i]);
} else if (exception != null && tags[i].exception() != null &&
tags[i].exception().subclassOf(exception)) {
output.tagList.add(tags[i]);
}
}
}
/**
* Add links for exceptions that are declared but not documented.
*/
private Content linkToUndocumentedDeclaredExceptions(
Type[] declaredExceptionTypes, Set<String> alreadyDocumented,
TagletWriter writer) {
Content result = writer.getOutputInstance();
//Add links to the exceptions declared but not documented.
for (int i = 0; i < declaredExceptionTypes.length; i++) {
if (declaredExceptionTypes[i].asClassDoc() != null &&
! alreadyDocumented.contains(
declaredExceptionTypes[i].asClassDoc().name()) &&
! alreadyDocumented.contains(
declaredExceptionTypes[i].asClassDoc().qualifiedName())) {
if (alreadyDocumented.size() == 0) {
result.addContent(writer.getThrowsHeader());
}
result.addContent(writer.throwsTagOutput(declaredExceptionTypes[i]));
alreadyDocumented.add(declaredExceptionTypes[i].asClassDoc().name());
}
}
return result;
}
/**
* Inherit throws documentation for exceptions that were declared but not
* documented.
*/
private Content inheritThrowsDocumentation(Doc holder,
Type[] declaredExceptionTypes, Set<String> alreadyDocumented,
TagletWriter writer) {
Content result = writer.getOutputInstance();
if (holder instanceof MethodDoc) {
Set<Tag> declaredExceptionTags = new LinkedHashSet<Tag>();
for (int j = 0; j < declaredExceptionTypes.length; j++) {
DocFinder.Output inheritedDoc =
DocFinder.search(new DocFinder.Input((MethodDoc) holder, this,
declaredExceptionTypes[j].typeName()));
if (inheritedDoc.tagList.size() == 0) {
inheritedDoc = DocFinder.search(new DocFinder.Input(
(MethodDoc) holder, this,
declaredExceptionTypes[j].qualifiedTypeName()));
}
declaredExceptionTags.addAll(inheritedDoc.tagList);
}
result.addContent(throwsTagsOutput(
declaredExceptionTags.toArray(new ThrowsTag[] {}),
writer, alreadyDocumented, false));
}
return result;
}
/**
* {@inheritDoc}
*/
public Content getTagletOutput(Doc holder, TagletWriter writer) {
ExecutableMemberDoc execHolder = (ExecutableMemberDoc) holder;
ThrowsTag[] tags = execHolder.throwsTags();
Content result = writer.getOutputInstance();
HashSet<String> alreadyDocumented = new HashSet<String>();
if (tags.length > 0) {
result.addContent(throwsTagsOutput(
execHolder.throwsTags(), writer, alreadyDocumented, true));
}
result.addContent(inheritThrowsDocumentation(holder,
execHolder.thrownExceptionTypes(), alreadyDocumented, writer));
result.addContent(linkToUndocumentedDeclaredExceptions(
execHolder.thrownExceptionTypes(), alreadyDocumented, writer));
return result;
}
/**
* Given an array of <code>Tag</code>s representing this custom
* tag, return its string representation.
* @param throwTags the array of <code>ThrowsTag</code>s to convert.
* @param writer the TagletWriter that will write this tag.
* @param alreadyDocumented the set of exceptions that have already
* been documented.
* @param allowDups True if we allow duplicate throws tags to be documented.
* @return the Content representation of this <code>Tag</code>.
*/
protected Content throwsTagsOutput(ThrowsTag[] throwTags,
TagletWriter writer, Set<String> alreadyDocumented, boolean allowDups) {
Content result = writer.getOutputInstance();
if (throwTags.length > 0) {
for (int i = 0; i < throwTags.length; ++i) {
ThrowsTag tt = throwTags[i];
ClassDoc cd = tt.exception();
if ((!allowDups) && (alreadyDocumented.contains(tt.exceptionName()) ||
(cd != null && alreadyDocumented.contains(cd.qualifiedName())))) {
continue;
}
if (alreadyDocumented.size() == 0) {
result.addContent(writer.getThrowsHeader());
}
result.addContent(writer.throwsTagOutput(tt));
alreadyDocumented.add(cd != null ?
cd.qualifiedName() : tt.exceptionName());
}
}
return result;
}
}

189
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/ValueTaglet.java Normal file
View File

@@ -0,0 +1,189 @@
/*
* Copyright (c) 2001, 2013, 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 com.sun.tools.doclets.internal.toolkit.taglets;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.Configuration;
import com.sun.tools.doclets.internal.toolkit.Content;
import com.sun.tools.doclets.internal.toolkit.util.*;
/**
* An inline Taglet representing the value tag. This tag should only be used with
* constant fields that have a value. It is used to access the value of constant
* fields. This inline tag has an optional field name parameter. If the name is
* specified, the constant value is retrieved from the specified field. A link
* is also created to the specified field. If a name is not specified, the value
* is retrieved for the field that the inline tag appears on. The name is specifed
* in the following format: [fully qualified class name]#[constant field name].
*
* <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
* @since 1.4
*/
public class ValueTaglet extends BaseInlineTaglet {
/**
* Construct a new ValueTaglet.
*/
public ValueTaglet() {
name = "value";
}
/**
* 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 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;
}
/**
* Given the name of the field, return the corresponding FieldDoc. Return null
* due to invalid use of value tag if the name is null or empty string and if
* the value tag is not used on a field.
*
* @param config the current configuration of the doclet.
* @param tag the value tag.
* @param name the name of the field to search for. The name should be in
* {@code <qualified class name>#<field name>} format. If the class name is omitted,
* it is assumed that the field is in the current class.
*
* @return the corresponding FieldDoc. If the name is null or empty string,
* return field that the value tag was used in. Return null if the name is null
* or empty string and if the value tag is not used on a field.
*/
private FieldDoc getFieldDoc(Configuration config, Tag tag, String name) {
if (name == null || name.length() == 0) {
//Base case: no label.
if (tag.holder() instanceof FieldDoc) {
return (FieldDoc) tag.holder();
} else {
// If the value tag does not specify a parameter which is a valid field and
// it is not used within the comments of a valid field, return null.
return null;
}
}
StringTokenizer st = new StringTokenizer(name, "#");
String memberName = null;
ClassDoc cd = null;
if (st.countTokens() == 1) {
//Case 2: @value in same class.
Doc holder = tag.holder();
if (holder instanceof MemberDoc) {
cd = ((MemberDoc) holder).containingClass();
} else if (holder instanceof ClassDoc) {
cd = (ClassDoc) holder;
}
memberName = st.nextToken();
} else {
//Case 3: @value in different class.
cd = config.root.classNamed(st.nextToken());
memberName = st.nextToken();
}
if (cd == null) {
return null;
}
FieldDoc[] fields = cd.fields();
for (int i = 0; i < fields.length; i++) {
if (fields[i].name().equals(memberName)) {
return fields[i];
}
}
return null;
}
/**
* {@inheritDoc}
*/
public Content getTagletOutput(Tag tag, TagletWriter writer) {
FieldDoc field = getFieldDoc(
writer.configuration(), tag, tag.text());
if (field == null) {
if (tag.text().isEmpty()) {
//Invalid use of @value
writer.getMsgRetriever().warning(tag.holder().position(),
"doclet.value_tag_invalid_use");
} else {
//Reference is unknown.
writer.getMsgRetriever().warning(tag.holder().position(),
"doclet.value_tag_invalid_reference", tag.text());
}
} else if (field.constantValue() != null) {
return writer.valueTagOutput(field,
field.constantValueExpression(),
! field.equals(tag.holder()));
} else {
//Referenced field is not a constant.
writer.getMsgRetriever().warning(tag.holder().position(),
"doclet.value_tag_invalid_constant", field.name());
}
return writer.getOutputInstance();
}
}

52
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/taglets/package-info.java Normal file
View File

@@ -0,0 +1,52 @@
/*
* Copyright (c) 2003, 2013, 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.
*/
/**
This package has classes used to generate Javadoc tag documentation.
Doclets no longer have to implement its own version of standard tags
such as &#64;param and &#64;throws. This is the single, doclet
implementation of each standard tag that is shared by all
doclets. Each doclet must have a taglet writer that takes a taglet
as input and writes doclet-dependent output. The taglet itself will
do the tag processing. For example, suppose we are outputing
&#64;throws tags. The taglet would:
<ul>
<li> Retrieve the list of throws tags to be documented.
<li> Replace {&#64;inheritDoc} with the appropriate documentation.
<li> Add throws documentation for exceptions that are declared in
the signature of the method but
not documented with the throws tags.
</ul>
After doing the steps above, the taglet would pass the information to
the taglet writer for writing. The taglets are essentially builders for
tags.
<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>
*/
@jdk.Exported(false)
package com.sun.tools.doclets.internal.toolkit.taglets;

284
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/ClassDocCatalog.java Normal file
View File

@@ -0,0 +1,284 @@
/*
* Copyright (c) 2001, 2012, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.Configuration;
/**
* This class acts as an artificial PackageDoc for classes specified
* on the command line when running Javadoc. For example, if you
* specify several classes from package java.lang, this class will catalog
* those classes so that we can retrieve all of the classes from a particular
* package later.
*
* <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
* @since 1.4
*/
public class ClassDocCatalog {
/**
* Stores the set of packages that the classes specified on the command line
* belong to. Note that the default package is "".
*/
private Set<String> packageSet;
/**
* Stores all classes for each package
*/
private Map<String,Set<ClassDoc>> allClasses;
/**
* Stores ordinary classes (excluding Exceptions and Errors) for each
* package
*/
private Map<String,Set<ClassDoc>> ordinaryClasses;
/**
* Stores exceptions for each package
*/
private Map<String,Set<ClassDoc>> exceptions;
/**
* Stores enums for each package.
*/
private Map<String,Set<ClassDoc>> enums;
/**
* Stores annotation types for each package.
*/
private Map<String,Set<ClassDoc>> annotationTypes;
/**
* Stores errors for each package
*/
private Map<String,Set<ClassDoc>> errors;
/**
* Stores interfaces for each package
*/
private Map<String,Set<ClassDoc>> interfaces;
private Configuration configuration;
/**
* Construct a new ClassDocCatalog.
*
* @param classdocs the array of ClassDocs to catalog
*/
public ClassDocCatalog (ClassDoc[] classdocs, Configuration config) {
init();
this.configuration = config;
for (int i = 0; i < classdocs.length; i++) {
addClassDoc(classdocs[i]);
}
}
/**
* Construct a new ClassDocCatalog.
*
*/
public ClassDocCatalog () {
init();
}
private void init() {
allClasses = new HashMap<String,Set<ClassDoc>>();
ordinaryClasses = new HashMap<String,Set<ClassDoc>>();
exceptions = new HashMap<String,Set<ClassDoc>>();
enums = new HashMap<String,Set<ClassDoc>>();
annotationTypes = new HashMap<String,Set<ClassDoc>>();
errors = new HashMap<String,Set<ClassDoc>>();
interfaces = new HashMap<String,Set<ClassDoc>>();
packageSet = new HashSet<String>();
}
/**
* Add the given class to the catalog.
* @param classdoc the ClassDoc to add to the catelog.
*/
public void addClassDoc(ClassDoc classdoc) {
if (classdoc == null) {
return;
}
addClass(classdoc, allClasses);
if (classdoc.isOrdinaryClass()) {
addClass(classdoc, ordinaryClasses);
} else if (classdoc.isException()) {
addClass(classdoc, exceptions);
} else if (classdoc.isEnum()) {
addClass(classdoc, enums);
} else if (classdoc.isAnnotationType()) {
addClass(classdoc, annotationTypes);
} else if (classdoc.isError()) {
addClass(classdoc, errors);
} else if (classdoc.isInterface()) {
addClass(classdoc, interfaces);
}
}
/**
* Add the given class to the given map.
* @param classdoc the ClassDoc to add to the catelog.
* @param map the Map to add the ClassDoc to.
*/
private void addClass(ClassDoc classdoc, Map<String,Set<ClassDoc>> map) {
PackageDoc pkg = classdoc.containingPackage();
if (pkg.isIncluded() || (configuration.nodeprecated && Util.isDeprecated(pkg))) {
//No need to catalog this class if it's package is
//included on the command line or if -nodeprecated option is set
// and the containing package is marked as deprecated.
return;
}
String key = Util.getPackageName(pkg);
Set<ClassDoc> s = map.get(key);
if (s == null) {
packageSet.add(key);
s = new HashSet<ClassDoc>();
}
s.add(classdoc);
map.put(key, s);
}
private ClassDoc[] getArray(Map<String,Set<ClassDoc>> m, String key) {
Set<ClassDoc> s = m.get(key);
if (s == null) {
return new ClassDoc[] {};
} else {
return s.toArray(new ClassDoc[] {});
}
}
/**
* Return all of the classes specified on the command-line that
* belong to the given package.
* @param pkgDoc the package to return the classes for.
*/
public ClassDoc[] allClasses(PackageDoc pkgDoc) {
return pkgDoc.isIncluded() ?
pkgDoc.allClasses() :
getArray(allClasses, Util.getPackageName(pkgDoc));
}
/**
* Return all of the classes specified on the command-line that
* belong to the given package.
* @param packageName the name of the package specified on the
* command-line.
*/
public ClassDoc[] allClasses(String packageName) {
return getArray(allClasses, packageName);
}
/**
* Return the array of package names that this catalog stores
* ClassDocs for.
*/
public String[] packageNames() {
return packageSet.toArray(new String[] {});
}
/**
* Return true if the given package is known to this catalog.
* @param packageName the name to check.
* @return true if this catalog has any information about
* classes in the given package.
*/
public boolean isKnownPackage(String packageName) {
return packageSet.contains(packageName);
}
/**
* Return all of the errors specified on the command-line
* that belong to the given package.
* @param packageName the name of the package specified on the
* command-line.
*/
public ClassDoc[] errors(String packageName) {
return getArray(errors, packageName);
}
/**
* Return all of the exceptions specified on the command-line
* that belong to the given package.
* @param packageName the name of the package specified on the
* command-line.
*/
public ClassDoc[] exceptions(String packageName) {
return getArray(exceptions, packageName);
}
/**
* Return all of the enums specified on the command-line
* that belong to the given package.
* @param packageName the name of the package specified on the
* command-line.
*/
public ClassDoc[] enums(String packageName) {
return getArray(enums, packageName);
}
/**
* Return all of the annotation types specified on the command-line
* that belong to the given package.
* @param packageName the name of the package specified on the
* command-line.
*/
public ClassDoc[] annotationTypes(String packageName) {
return getArray(annotationTypes, packageName);
}
/**
* Return all of the interfaces specified on the command-line
* that belong to the given package.
* @param packageName the name of the package specified on the
* command-line.
*/
public ClassDoc[] interfaces(String packageName) {
return getArray(interfaces, packageName);
}
/**
* Return all of the ordinary classes specified on the command-line
* that belong to the given package.
* @param packageName the name of the package specified on the
* command-line.
*/
public ClassDoc[] ordinaryClasses(String packageName) {
return getArray(ordinaryClasses, packageName);
}
}

387
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/ClassTree.java Normal file
View File

@@ -0,0 +1,387 @@
/*
* Copyright (c) 1998, 2013, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
/**
* Build Class Hierarchy for all the Classes. This class builds the Class
* Tree and the Interface Tree separately.
*
* <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>
*
* @see java.util.HashMap
* @see java.util.List
* @see com.sun.javadoc.Type
* @see com.sun.javadoc.ClassDoc
* @author Atul M Dambalkar
*/
public class ClassTree {
/**
* List of baseclasses. Contains only java.lang.Object. Can be used to get
* the mapped listing of sub-classes.
*/
private List<ClassDoc> baseclasses = new ArrayList<ClassDoc>();
/**
* Mapping for each Class with their SubClasses
*/
private Map<ClassDoc,List<ClassDoc>> subclasses = new HashMap<ClassDoc,List<ClassDoc>>();
/**
* List of base-interfaces. Contains list of all the interfaces who do not
* have super-interfaces. Can be used to get the mapped listing of
* sub-interfaces.
*/
private List<ClassDoc> baseinterfaces = new ArrayList<ClassDoc>();
/**
* Mapping for each Interface with their SubInterfaces
*/
private Map<ClassDoc,List<ClassDoc>> subinterfaces = new HashMap<ClassDoc,List<ClassDoc>>();
private List<ClassDoc> baseEnums = new ArrayList<ClassDoc>();
private Map<ClassDoc,List<ClassDoc>> subEnums = new HashMap<ClassDoc,List<ClassDoc>>();
private List<ClassDoc> baseAnnotationTypes = new ArrayList<ClassDoc>();
private Map<ClassDoc,List<ClassDoc>> subAnnotationTypes = new HashMap<ClassDoc,List<ClassDoc>>();
/**
* Mapping for each Interface with classes who implement it.
*/
private Map<ClassDoc,List<ClassDoc>> implementingclasses = new HashMap<ClassDoc,List<ClassDoc>>();
/**
* Constructor. Build the Tree using the Root of this Javadoc run.
*
* @param configuration the configuration of the doclet.
* @param noDeprecated Don't add deprecated classes in the class tree, if
* true.
*/
public ClassTree(Configuration configuration, boolean noDeprecated) {
configuration.message.notice("doclet.Building_Tree");
buildTree(configuration.root.classes(), configuration);
}
/**
* Constructor. Build the Tree using the Root of this Javadoc run.
*
* @param root Root of the Document.
* @param configuration The curren configuration of the doclet.
*/
public ClassTree(RootDoc root, Configuration configuration) {
buildTree(root.classes(), configuration);
}
/**
* Constructor. Build the tree for the given array of classes.
*
* @param classes Array of classes.
* @param configuration The curren configuration of the doclet.
*/
public ClassTree(ClassDoc[] classes, Configuration configuration) {
buildTree(classes, configuration);
}
/**
* Generate mapping for the sub-classes for every class in this run.
* Return the sub-class list for java.lang.Object which will be having
* sub-class listing for itself and also for each sub-class itself will
* have their own sub-class lists.
*
* @param classes all the classes in this run.
* @param configuration the current configuration of the doclet.
*/
private void buildTree(ClassDoc[] classes, Configuration configuration) {
for (int i = 0; i < classes.length; i++) {
// In the tree page (e.g overview-tree.html) do not include
// information of classes which are deprecated or are a part of a
// deprecated package.
if (configuration.nodeprecated &&
(Util.isDeprecated(classes[i]) ||
Util.isDeprecated(classes[i].containingPackage()))) {
continue;
}
if (configuration.javafx
&& classes[i].tags("treatAsPrivate").length > 0) {
continue;
}
if (classes[i].isEnum()) {
processType(classes[i], configuration, baseEnums, subEnums);
} else if (classes[i].isClass()) {
processType(classes[i], configuration, baseclasses, subclasses);
} else if (classes[i].isInterface()) {
processInterface(classes[i]);
List<ClassDoc> list = implementingclasses.get(classes[i]);
if (list != null) {
Collections.sort(list);
}
} else if (classes[i].isAnnotationType()) {
processType(classes[i], configuration, baseAnnotationTypes,
subAnnotationTypes);
}
}
Collections.sort(baseinterfaces);
for (Iterator<List<ClassDoc>> it = subinterfaces.values().iterator(); it.hasNext(); ) {
Collections.sort(it.next());
}
for (Iterator<List<ClassDoc>> it = subclasses.values().iterator(); it.hasNext(); ) {
Collections.sort(it.next());
}
}
/**
* For the class passed map it to it's own sub-class listing.
* For the Class passed, get the super class,
* if superclass is non null, (it is not "java.lang.Object")
* get the "value" from the hashmap for this key Class
* if entry not found create one and get that.
* add this Class as a sub class in the list
* Recurse till hits java.lang.Object Null SuperClass.
*
* @param cd class for which sub-class mapping to be generated.
* @param configuration the current configurtation of the doclet.
*/
private void processType(ClassDoc cd, Configuration configuration,
List<ClassDoc> bases, Map<ClassDoc,List<ClassDoc>> subs) {
ClassDoc superclass = Util.getFirstVisibleSuperClassCD(cd, configuration);
if (superclass != null) {
if (!add(subs, superclass, cd)) {
return;
} else {
processType(superclass, configuration, bases, subs);
}
} else { // cd is java.lang.Object, add it once to the list
if (!bases.contains(cd)) {
bases.add(cd);
}
}
List<Type> intfacs = Util.getAllInterfaces(cd, configuration);
for (Iterator<Type> iter = intfacs.iterator(); iter.hasNext();) {
add(implementingclasses, iter.next().asClassDoc(), cd);
}
}
/**
* For the interface passed get the interfaces which it extends, and then
* put this interface in the sub-interface list of those interfaces. Do it
* recursively. If a interface doesn't have super-interface just attach
* that interface in the list of all the baseinterfaces.
*
* @param cd Interface under consideration.
*/
private void processInterface(ClassDoc cd) {
ClassDoc[] intfacs = cd.interfaces();
if (intfacs.length > 0) {
for (int i = 0; i < intfacs.length; i++) {
if (!add(subinterfaces, intfacs[i], cd)) {
return;
} else {
processInterface(intfacs[i]); // Recurse
}
}
} else {
// we need to add all the interfaces who do not have
// super-interfaces to baseinterfaces list to traverse them
if (!baseinterfaces.contains(cd)) {
baseinterfaces.add(cd);
}
}
}
/**
* Adjust the Class Tree. Add the class interface in to it's super-class'
* or super-interface's sub-interface list.
*
* @param map the entire map.
* @param superclass java.lang.Object or the super-interface.
* @param cd sub-interface to be mapped.
* @returns boolean true if class added, false if class already processed.
*/
private boolean add(Map<ClassDoc,List<ClassDoc>> map, ClassDoc superclass, ClassDoc cd) {
List<ClassDoc> list = map.get(superclass);
if (list == null) {
list = new ArrayList<ClassDoc>();
map.put(superclass, list);
}
if (list.contains(cd)) {
return false;
} else {
list.add(cd);
}
return true;
}
/**
* From the map return the list of sub-classes or sub-interfaces. If list
* is null create a new one and return it.
*
* @param map The entire map.
* @param cd class for which the sub-class list is requested.
* @returns List Sub-Class list for the class passed.
*/
private List<ClassDoc> get(Map<ClassDoc,List<ClassDoc>> map, ClassDoc cd) {
List<ClassDoc> list = map.get(cd);
if (list == null) {
return new ArrayList<ClassDoc>();
}
return list;
}
/**
* Return the sub-class list for the class passed.
*
* @param cd class whose sub-class list is required.
*/
public List<ClassDoc> subclasses(ClassDoc cd) {
return get(subclasses, cd);
}
/**
* Return the sub-interface list for the interface passed.
*
* @param cd interface whose sub-interface list is required.
*/
public List<ClassDoc> subinterfaces(ClassDoc cd) {
return get(subinterfaces, cd);
}
/**
* Return the list of classes which implement the interface passed.
*
* @param cd interface whose implementing-classes list is required.
*/
public List<ClassDoc> implementingclasses(ClassDoc cd) {
List<ClassDoc> result = get(implementingclasses, cd);
List<ClassDoc> subinterfaces = allSubs(cd, false);
//If class x implements a subinterface of cd, then it follows
//that class x implements cd.
Iterator<ClassDoc> implementingClassesIter, subInterfacesIter = subinterfaces.listIterator();
ClassDoc c;
while(subInterfacesIter.hasNext()){
implementingClassesIter = implementingclasses(
subInterfacesIter.next()).listIterator();
while(implementingClassesIter.hasNext()){
c = implementingClassesIter.next();
if(! result.contains(c)){
result.add(c);
}
}
}
Collections.sort(result);
return result;
}
/**
* Return the sub-class/interface list for the class/interface passed.
*
* @param cd class/interface whose sub-class/interface list is required.
* @param isEnum true if the subclasses should be forced to come from the
* enum tree.
*/
public List<ClassDoc> subs(ClassDoc cd, boolean isEnum) {
if (isEnum) {
return get(subEnums, cd);
} else if (cd.isAnnotationType()) {
return get(subAnnotationTypes, cd);
} else if (cd.isInterface()) {
return get(subinterfaces, cd);
} else if (cd.isClass()) {
return get(subclasses, cd);
} else {
return null;
}
}
/**
* Return a list of all direct or indirect, sub-classes and subinterfaces
* of the ClassDoc argument.
*
* @param cd ClassDoc whose sub-classes or sub-interfaces are requested.
* @param isEnum true if the subclasses should be forced to come from the
* enum tree.
*/
public List<ClassDoc> allSubs(ClassDoc cd, boolean isEnum) {
List<ClassDoc> list = subs(cd, isEnum);
for (int i = 0; i < list.size(); i++) {
cd = list.get(i);
List<ClassDoc> tlist = subs(cd, isEnum);
for (int j = 0; j < tlist.size(); j++) {
ClassDoc tcd = tlist.get(j);
if (!list.contains(tcd)) {
list.add(tcd);
}
}
}
Collections.sort(list);
return list;
}
/**
* Return the base-classes list. This will have only one element namely
* thw classdoc for java.lang.Object, since this is the base class for all
* classes.
*/
public List<ClassDoc> baseclasses() {
return baseclasses;
}
/**
* Return the list of base interfaces. This is the list of interfaces
* which do not have super-interface.
*/
public List<ClassDoc> baseinterfaces() {
return baseinterfaces;
}
/**
* Return the list of base enums. This is the list of enums
* which do not have super-enums.
*/
public List<ClassDoc> baseEnums() {
return baseEnums;
}
/**
* Return the list of base annotation types. This is the list of
* annotation types which do not have super-annotation types.
*/
public List<ClassDoc> baseAnnotationTypes() {
return baseAnnotationTypes;
}
}

494
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/ClassUseMapper.java Normal file
View File

@@ -0,0 +1,494 @@
/*
* Copyright (c) 1998, 2013, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.util.*;
import com.sun.javadoc.*;
/**
* Map all class uses for a given class.
*
* <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>
*
* @since 1.2
* @author Robert G. Field
*/
public class ClassUseMapper {
private final ClassTree classtree;
/**
* Mapping of ClassDocs to set of PackageDoc used by that class.
* Entries may be null.
*/
public Map<String,Set<PackageDoc>> classToPackage = new HashMap<String,Set<PackageDoc>>();
/**
* Mapping of Annotations to set of PackageDoc that use the annotation.
*/
public Map<String,List<PackageDoc>> classToPackageAnnotations = new HashMap<String,List<PackageDoc>>();
/**
* Mapping of ClassDocs to set of ClassDoc used by that class.
* Entries may be null.
*/
public Map<String,Set<ClassDoc>> classToClass = new HashMap<String,Set<ClassDoc>>();
/**
* Mapping of ClassDocs to list of ClassDoc which are direct or
* indirect subclasses of that class.
* Entries may be null.
*/
public Map<String,List<ClassDoc>> classToSubclass = new HashMap<String,List<ClassDoc>>();
/**
* Mapping of ClassDocs to list of ClassDoc which are direct or
* indirect subinterfaces of that interface.
* Entries may be null.
*/
public Map<String,List<ClassDoc>> classToSubinterface = new HashMap<String,List<ClassDoc>>();
/**
* Mapping of ClassDocs to list of ClassDoc which implement
* this interface.
* Entries may be null.
*/
public Map<String,List<ClassDoc>> classToImplementingClass = new HashMap<String,List<ClassDoc>>();
/**
* Mapping of ClassDocs to list of FieldDoc declared as that class.
* Entries may be null.
*/
public Map<String,List<FieldDoc>> classToField = new HashMap<String,List<FieldDoc>>();
/**
* Mapping of ClassDocs to list of MethodDoc returning that class.
* Entries may be null.
*/
public Map<String,List<MethodDoc>> classToMethodReturn = new HashMap<String,List<MethodDoc>>();
/**
* Mapping of ClassDocs to list of MethodDoc having that class
* as an arg.
* Entries may be null.
*/
public Map<String,List<ExecutableMemberDoc>> classToMethodArgs = new HashMap<String,List<ExecutableMemberDoc>>();
/**
* Mapping of ClassDocs to list of MethodDoc which throws that class.
* Entries may be null.
*/
public Map<String,List<ExecutableMemberDoc>> classToMethodThrows = new HashMap<String,List<ExecutableMemberDoc>>();
/**
* Mapping of ClassDocs to list of ConstructorDoc having that class
* as an arg.
* Entries may be null.
*/
public Map<String,List<ExecutableMemberDoc>> classToConstructorArgs = new HashMap<String,List<ExecutableMemberDoc>>();
/**
* Mapping of ClassDocs to list of ConstructorDoc which throws that class.
* Entries may be null.
*/
public Map<String,List<ExecutableMemberDoc>> classToConstructorThrows = new HashMap<String,List<ExecutableMemberDoc>>();
/**
* The mapping of AnnotationTypeDocs to constructors that use them.
*/
public Map<String,List<ConstructorDoc>> classToConstructorAnnotations = new HashMap<String,List<ConstructorDoc>>();
/**
* The mapping of AnnotationTypeDocs to Constructor parameters that use them.
*/
public Map<String,List<ExecutableMemberDoc>> classToConstructorParamAnnotation = new HashMap<String,List<ExecutableMemberDoc>>();
/**
* The mapping of ClassDocs to Constructor arguments that use them as type parameters.
*/
public Map<String,List<ExecutableMemberDoc>> classToConstructorDocArgTypeParam = new HashMap<String,List<ExecutableMemberDoc>>();
/**
* The mapping of ClassDocs to ClassDocs that use them as type parameters.
*/
public Map<String,List<ClassDoc>> classToClassTypeParam = new HashMap<String,List<ClassDoc>>();
/**
* The mapping of AnnotationTypeDocs to ClassDocs that use them.
*/
public Map<String,List<ClassDoc>> classToClassAnnotations = new HashMap<String,List<ClassDoc>>();
/**
* The mapping of ClassDocs to ExecutableMemberDocs that use them as type parameters.
*/
public Map<String,List<MethodDoc>> classToExecMemberDocTypeParam = new HashMap<String,List<MethodDoc>>();
/**
* The mapping of ClassDocs to ExecutableMemberDocs arguments that use them as type parameters.
*/
public Map<String,List<ExecutableMemberDoc>> classToExecMemberDocArgTypeParam = new HashMap<String,List<ExecutableMemberDoc>>();
/**
* The mapping of AnnotationTypeDocs to ExecutableMemberDocs that use them.
*/
public Map<String,List<MethodDoc>> classToExecMemberDocAnnotations = new HashMap<String,List<MethodDoc>>();
/**
* The mapping of ClassDocs to ExecutableMemberDocs that have return type
* with type parameters of that class.
*/
public Map<String,List<MethodDoc>> classToExecMemberDocReturnTypeParam = new HashMap<String,List<MethodDoc>>();
/**
* The mapping of AnnotationTypeDocs to MethodDoc parameters that use them.
*/
public Map<String,List<ExecutableMemberDoc>> classToExecMemberDocParamAnnotation = new HashMap<String,List<ExecutableMemberDoc>>();
/**
* The mapping of ClassDocs to FieldDocs that use them as type parameters.
*/
public Map<String,List<FieldDoc>> classToFieldDocTypeParam = new HashMap<String,List<FieldDoc>>();
/**
* The mapping of AnnotationTypeDocs to FieldDocs that use them.
*/
public Map<String,List<FieldDoc>> annotationToFieldDoc = new HashMap<String,List<FieldDoc>>();
public ClassUseMapper(RootDoc root, ClassTree classtree) {
this.classtree = classtree;
// Map subclassing, subinterfacing implementing, ...
for (Iterator<ClassDoc> it = classtree.baseclasses().iterator(); it.hasNext();) {
subclasses(it.next());
}
for (Iterator<ClassDoc> it = classtree.baseinterfaces().iterator(); it.hasNext();) {
// does subinterfacing as side-effect
implementingClasses(it.next());
}
// Map methods, fields, constructors using a class.
ClassDoc[] classes = root.classes();
for (int i = 0; i < classes.length; i++) {
PackageDoc pkg = classes[i].containingPackage();
mapAnnotations(classToPackageAnnotations, pkg, pkg);
ClassDoc cd = classes[i];
mapTypeParameters(classToClassTypeParam, cd, cd);
mapAnnotations(classToClassAnnotations, cd, cd);
FieldDoc[] fields = cd.fields();
for (int j = 0; j < fields.length; j++) {
FieldDoc fd = fields[j];
mapTypeParameters(classToFieldDocTypeParam, fd, fd);
mapAnnotations(annotationToFieldDoc, fd, fd);
if (! fd.type().isPrimitive()) {
add(classToField, fd.type().asClassDoc(), fd);
}
}
ConstructorDoc[] cons = cd.constructors();
for (int j = 0; j < cons.length; j++) {
mapAnnotations(classToConstructorAnnotations, cons[j], cons[j]);
mapExecutable(cons[j]);
}
MethodDoc[] meths = cd.methods();
for (int j = 0; j < meths.length; j++) {
MethodDoc md = meths[j];
mapExecutable(md);
mapTypeParameters(classToExecMemberDocTypeParam, md, md);
mapAnnotations(classToExecMemberDocAnnotations, md, md);
if (! (md.returnType().isPrimitive() || md.returnType() instanceof TypeVariable)) {
mapTypeParameters(classToExecMemberDocReturnTypeParam,
md.returnType(), md);
add(classToMethodReturn, md.returnType().asClassDoc(), md);
}
}
}
}
/**
* Return all subclasses of a class AND fill-in classToSubclass map.
*/
private Collection<ClassDoc> subclasses(ClassDoc cd) {
Collection<ClassDoc> ret = classToSubclass.get(cd.qualifiedName());
if (ret == null) {
ret = new TreeSet<ClassDoc>();
List<ClassDoc> subs = classtree.subclasses(cd);
if (subs != null) {
ret.addAll(subs);
for (Iterator<ClassDoc> it = subs.iterator(); it.hasNext();) {
ret.addAll(subclasses(it.next()));
}
}
addAll(classToSubclass, cd, ret);
}
return ret;
}
/**
* Return all subinterfaces of an interface AND fill-in classToSubinterface map.
*/
private Collection<ClassDoc> subinterfaces(ClassDoc cd) {
Collection<ClassDoc> ret = classToSubinterface.get(cd.qualifiedName());
if (ret == null) {
ret = new TreeSet<ClassDoc>();
List<ClassDoc> subs = classtree.subinterfaces(cd);
if (subs != null) {
ret.addAll(subs);
for (Iterator<ClassDoc> it = subs.iterator(); it.hasNext();) {
ret.addAll(subinterfaces(it.next()));
}
}
addAll(classToSubinterface, cd, ret);
}
return ret;
}
/**
* Return all implementing classes of an interface (including
* all subclasses of implementing classes and all classes
* implementing subinterfaces) AND fill-in both classToImplementingClass
* and classToSubinterface maps.
*/
private Collection<ClassDoc> implementingClasses(ClassDoc cd) {
Collection<ClassDoc> ret = classToImplementingClass.get(cd.qualifiedName());
if (ret == null) {
ret = new TreeSet<ClassDoc>();
List<ClassDoc> impl = classtree.implementingclasses(cd);
if (impl != null) {
ret.addAll(impl);
for (Iterator<ClassDoc> it = impl.iterator(); it.hasNext();) {
ret.addAll(subclasses(it.next()));
}
}
for (Iterator<ClassDoc> it = subinterfaces(cd).iterator(); it.hasNext();) {
ret.addAll(implementingClasses(it.next()));
}
addAll(classToImplementingClass, cd, ret);
}
return ret;
}
/**
* Determine classes used by a method or constructor, so they can be
* inverse mapped.
*/
private void mapExecutable(ExecutableMemberDoc em) {
Parameter[] params = em.parameters();
boolean isConstructor = em.isConstructor();
List<Type> classArgs = new ArrayList<Type>();
for (int k = 0; k < params.length; k++) {
Type pcd = params[k].type();
// primitives don't get mapped, also avoid dups
if ((! params[k].type().isPrimitive()) &&
! classArgs.contains(pcd) &&
! (pcd instanceof TypeVariable)) {
add(isConstructor? classToConstructorArgs :classToMethodArgs,
pcd.asClassDoc(), em);
classArgs.add(pcd);
mapTypeParameters(isConstructor?
classToConstructorDocArgTypeParam : classToExecMemberDocArgTypeParam,
pcd, em);
}
mapAnnotations(
isConstructor ?
classToConstructorParamAnnotation :
classToExecMemberDocParamAnnotation,
params[k], em);
}
ClassDoc[] thr = em.thrownExceptions();
for (int k = 0; k < thr.length; k++) {
add(isConstructor? classToConstructorThrows : classToMethodThrows,
thr[k], em);
}
}
private <T> List<T> refList(Map<String,List<T>> map, ClassDoc cd) {
List<T> list = map.get(cd.qualifiedName());
if (list == null) {
List<T> l = new ArrayList<T>();
list = l;
map.put(cd.qualifiedName(), list);
}
return list;
}
private Set<PackageDoc> packageSet(ClassDoc cd) {
Set<PackageDoc> pkgSet = classToPackage.get(cd.qualifiedName());
if (pkgSet == null) {
pkgSet = new TreeSet<PackageDoc>();
classToPackage.put(cd.qualifiedName(), pkgSet);
}
return pkgSet;
}
private Set<ClassDoc> classSet(ClassDoc cd) {
Set<ClassDoc> clsSet = classToClass.get(cd.qualifiedName());
if (clsSet == null) {
Set<ClassDoc> s = new TreeSet<ClassDoc>();
clsSet = s;
classToClass.put(cd.qualifiedName(), clsSet);
}
return clsSet;
}
private <T extends ProgramElementDoc> void add(Map<String,List<T>> map, ClassDoc cd, T ref) {
// add to specified map
refList(map, cd).add(ref);
// add ref's package to package map and class map
packageSet(cd).add(ref.containingPackage());
classSet(cd).add(ref instanceof MemberDoc?
((MemberDoc)ref).containingClass() :
(ClassDoc)ref);
}
private void addAll(Map<String,List<ClassDoc>> map, ClassDoc cd, Collection<ClassDoc> refs) {
if (refs == null) {
return;
}
// add to specified map
refList(map, cd).addAll(refs);
Set<PackageDoc> pkgSet = packageSet(cd);
Set<ClassDoc> clsSet = classSet(cd);
// add ref's package to package map and class map
for (Iterator<ClassDoc> it = refs.iterator(); it.hasNext();) {
ClassDoc cls = it.next();
pkgSet.add(cls.containingPackage());
clsSet.add(cls);
}
}
/**
* Map the ClassDocs to the ProgramElementDocs that use them as
* type parameters.
*
* @param map the map the insert the information into.
* @param doc the doc whose type parameters are being checked.
* @param holder the holder that owns the type parameters.
*/
private <T extends ProgramElementDoc> void mapTypeParameters(Map<String,List<T>> map, Object doc,
T holder) {
TypeVariable[] typeVariables;
if (doc instanceof ClassDoc) {
typeVariables = ((ClassDoc) doc).typeParameters();
} else if (doc instanceof WildcardType) {
Type[] extendsBounds = ((WildcardType) doc).extendsBounds();
for (int k = 0; k < extendsBounds.length; k++) {
addTypeParameterToMap(map, extendsBounds[k], holder);
}
Type[] superBounds = ((WildcardType) doc).superBounds();
for (int k = 0; k < superBounds.length; k++) {
addTypeParameterToMap(map, superBounds[k], holder);
}
return;
} else if (doc instanceof ParameterizedType) {
Type[] typeArguments = ((ParameterizedType) doc).typeArguments();
for (int k = 0; k < typeArguments.length; k++) {
addTypeParameterToMap(map, typeArguments[k], holder);
}
return;
} else if (doc instanceof ExecutableMemberDoc) {
typeVariables = ((ExecutableMemberDoc) doc).typeParameters();
} else if (doc instanceof FieldDoc) {
Type fieldType = ((FieldDoc) doc).type();
mapTypeParameters(map, fieldType, holder);
return;
} else {
return;
}
for (int i = 0; i < typeVariables.length; i++) {
Type[] bounds = typeVariables[i].bounds();
for (int j = 0; j < bounds.length; j++) {
addTypeParameterToMap(map, bounds[j], holder);
}
}
}
/**
* Map the AnnotationType to the ProgramElementDocs that use them as
* type parameters.
*
* @param map the map the insert the information into.
* @param doc the doc whose type parameters are being checked.
* @param holder the holder that owns the type parameters.
*/
private <T extends ProgramElementDoc> void mapAnnotations(Map<String,List<T>> map, Object doc,
T holder) {
AnnotationDesc[] annotations;
boolean isPackage = false;
if (doc instanceof ProgramElementDoc) {
annotations = ((ProgramElementDoc) doc).annotations();
} else if (doc instanceof PackageDoc) {
annotations = ((PackageDoc) doc).annotations();
isPackage = true;
} else if (doc instanceof Parameter) {
annotations = ((Parameter) doc).annotations();
} else {
throw new DocletAbortException("should not happen");
}
for (int i = 0; i < annotations.length; i++) {
AnnotationTypeDoc annotationDoc = annotations[i].annotationType();
if (isPackage)
refList(map, annotationDoc).add(holder);
else
add(map, annotationDoc, holder);
}
}
/**
* Map the AnnotationType to the ProgramElementDocs that use them as
* type parameters.
*
* @param map the map the insert the information into.
* @param doc the doc whose type parameters are being checked.
* @param holder the holder that owns the type parameters.
*/
private <T extends PackageDoc> void mapAnnotations(Map<String,List<T>> map, PackageDoc doc,
T holder) {
AnnotationDesc[] annotations;
annotations = doc.annotations();
for (int i = 0; i < annotations.length; i++) {
AnnotationTypeDoc annotationDoc = annotations[i].annotationType();
refList(map, annotationDoc).add(holder);
}
}
private <T extends ProgramElementDoc> void addTypeParameterToMap(Map<String,List<T>> map, Type type,
T holder) {
if (type instanceof ClassDoc) {
add(map, (ClassDoc) type, holder);
} else if (type instanceof ParameterizedType) {
add(map, ((ParameterizedType) type).asClassDoc(), holder);
}
mapTypeParameters(map, type, holder);
}
}

43
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/CommentedMethodFinder.java Normal file
View File

@@ -0,0 +1,43 @@
/*
* Copyright (c) 1999, 2012, 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 com.sun.tools.doclets.internal.toolkit.util;
import com.sun.javadoc.*;
/**
* Find a commented method.
*
* <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 CommentedMethodFinder extends MethodFinder {
public boolean isCorrectMethod(MethodDoc method) {
return method.inlineTags().length > 0;
}
}

168
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/DeprecatedAPIListBuilder.java Normal file
View File

@@ -0,0 +1,168 @@
/*
* Copyright (c) 1998, 2012, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.Configuration;
/**
* Build list of all the deprecated packages, classes, constructors, fields and methods.
*
* <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 Atul M Dambalkar
*/
public class DeprecatedAPIListBuilder {
public static final int NUM_TYPES = 12;
public static final int PACKAGE = 0;
public static final int INTERFACE = 1;
public static final int CLASS = 2;
public static final int ENUM = 3;
public static final int EXCEPTION = 4;
public static final int ERROR = 5;
public static final int ANNOTATION_TYPE = 6;
public static final int FIELD = 7;
public static final int METHOD = 8;
public static final int CONSTRUCTOR = 9;
public static final int ENUM_CONSTANT = 10;
public static final int ANNOTATION_TYPE_MEMBER = 11;
/**
* List of deprecated type Lists.
*/
private List<List<Doc>> deprecatedLists;
/**
* Constructor.
*
* @param configuration the current configuration of the doclet
*/
public DeprecatedAPIListBuilder(Configuration configuration) {
deprecatedLists = new ArrayList<List<Doc>>();
for (int i = 0; i < NUM_TYPES; i++) {
deprecatedLists.add(i, new ArrayList<Doc>());
}
buildDeprecatedAPIInfo(configuration);
}
/**
* Build the sorted list of all the deprecated APIs in this run.
* Build separate lists for deprecated packages, classes, constructors,
* methods and fields.
*
* @param configuration the current configuration of the doclet.
*/
private void buildDeprecatedAPIInfo(Configuration configuration) {
PackageDoc[] packages = configuration.packages;
PackageDoc pkg;
for (int c = 0; c < packages.length; c++) {
pkg = packages[c];
if (Util.isDeprecated(pkg)) {
getList(PACKAGE).add(pkg);
}
}
ClassDoc[] classes = configuration.root.classes();
for (int i = 0; i < classes.length; i++) {
ClassDoc cd = classes[i];
if (Util.isDeprecated(cd)) {
if (cd.isOrdinaryClass()) {
getList(CLASS).add(cd);
} else if (cd.isInterface()) {
getList(INTERFACE).add(cd);
} else if (cd.isException()) {
getList(EXCEPTION).add(cd);
} else if (cd.isEnum()) {
getList(ENUM).add(cd);
} else if (cd.isError()) {
getList(ERROR).add(cd);
} else if (cd.isAnnotationType()) {
getList(ANNOTATION_TYPE).add(cd);
}
}
composeDeprecatedList(getList(FIELD), cd.fields());
composeDeprecatedList(getList(METHOD), cd.methods());
composeDeprecatedList(getList(CONSTRUCTOR), cd.constructors());
if (cd.isEnum()) {
composeDeprecatedList(getList(ENUM_CONSTANT), cd.enumConstants());
}
if (cd.isAnnotationType()) {
composeDeprecatedList(getList(ANNOTATION_TYPE_MEMBER),
((AnnotationTypeDoc) cd).elements());
}
}
sortDeprecatedLists();
}
/**
* Add the members into a single list of deprecated members.
*
* @param list List of all the particular deprecated members, e.g. methods.
* @param members members to be added in the list.
*/
private void composeDeprecatedList(List<Doc> list, MemberDoc[] members) {
for (int i = 0; i < members.length; i++) {
if (Util.isDeprecated(members[i])) {
list.add(members[i]);
}
}
}
/**
* Sort the deprecated lists for class kinds, fields, methods and
* constructors.
*/
private void sortDeprecatedLists() {
for (int i = 0; i < NUM_TYPES; i++) {
Collections.sort(getList(i));
}
}
/**
* Return the list of deprecated Doc objects of a given type.
*
* @param type the constant representing the type of list being returned.
*/
public List<Doc> getList(int type) {
return deprecatedLists.get(type);
}
/**
* Return true if the list of a given type has size greater than 0.
*
* @param type the type of list being checked.
*/
public boolean hasDocumentation(int type) {
return (deprecatedLists.get(type)).size() > 0;
}
}

259
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/DocFile.java Normal file
View File

@@ -0,0 +1,259 @@
/*
* Copyright (c) 1998, 2013, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.UnsupportedEncodingException;
import java.io.Writer;
import javax.tools.JavaFileManager.Location;
import javax.tools.StandardLocation;
import com.sun.tools.doclets.internal.toolkit.Configuration;
/**
* Abstraction for handling files, which may be specified directly
* (e.g. via a path on the command line) or relative to a Location.
*
* <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>
*
* @since 8
*/
public abstract class DocFile {
/** Create a DocFile for a directory. */
public static DocFile createFileForDirectory(Configuration configuration, String file) {
return DocFileFactory.getFactory(configuration).createFileForDirectory(file);
}
/** Create a DocFile for a file that will be opened for reading. */
public static DocFile createFileForInput(Configuration configuration, String file) {
return DocFileFactory.getFactory(configuration).createFileForInput(file);
}
/** Create a DocFile for a file that will be opened for writing. */
public static DocFile createFileForOutput(Configuration configuration, DocPath path) {
return DocFileFactory.getFactory(configuration).createFileForOutput(path);
}
private final Configuration configuration;
/**
* The location for this file. Maybe null if the file was created without
* a location or path.
*/
protected final Location location;
/**
* The path relative to the (output) location. Maybe null if the file was
* created without a location or path.
*/
protected final DocPath path;
/**
* List the directories and files found in subdirectories along the
* elements of the given location.
* @param configuration the doclet configuration
* @param location currently, only {@link StandardLocation#SOURCE_PATH} is supported.
* @param path the subdirectory of the directories of the location for which to
* list files
*/
public static Iterable<DocFile> list(Configuration configuration, Location location, DocPath path) {
return DocFileFactory.getFactory(configuration).list(location, path);
}
/** Create a DocFile without a location or path */
protected DocFile(Configuration configuration) {
this.configuration = configuration;
this.location = null;
this.path = null;
}
/** Create a DocFile for a given location and relative path. */
protected DocFile(Configuration configuration, Location location, DocPath path) {
this.configuration = configuration;
this.location = location;
this.path = path;
}
/** Open an input stream for the file. */
public abstract InputStream openInputStream() throws IOException;
/**
* Open an output stream for the file.
* The file must have been created with a location of
* {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT}
* and a corresponding relative path.
*/
public abstract OutputStream openOutputStream() throws IOException, UnsupportedEncodingException;
/**
* Open an writer for the file, using the encoding (if any) given in the
* doclet configuration.
* The file must have been created with a location of
* {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} and a corresponding relative path.
*/
public abstract Writer openWriter() throws IOException, UnsupportedEncodingException;
/**
* Copy the contents of another file directly to this file.
*/
public void copyFile(DocFile fromFile) throws IOException {
InputStream input = fromFile.openInputStream();
OutputStream output = openOutputStream();
try {
byte[] bytearr = new byte[1024];
int len;
while ((len = input.read(bytearr)) != -1) {
output.write(bytearr, 0, len);
}
} catch (FileNotFoundException exc) {
} catch (SecurityException exc) {
} finally {
input.close();
output.close();
}
}
/**
* Copy the contents of a resource file to this file.
* @param resource the path of the resource, relative to the package of this class
* @param overwrite whether or not to overwrite the file if it already exists
* @param replaceNewLine if false, the file is copied as a binary file;
* if true, the file is written line by line, using the platform line
* separator
*/
public void copyResource(DocPath resource, boolean overwrite, boolean replaceNewLine) {
if (exists() && !overwrite)
return;
try {
InputStream in = Configuration.class.getResourceAsStream(resource.getPath());
if (in == null)
return;
OutputStream out = openOutputStream();
try {
if (!replaceNewLine) {
byte[] buf = new byte[2048];
int n;
while((n = in.read(buf))>0) out.write(buf,0,n);
} else {
BufferedReader reader = new BufferedReader(new InputStreamReader(in));
BufferedWriter writer;
if (configuration.docencoding == null) {
writer = new BufferedWriter(new OutputStreamWriter(out));
} else {
writer = new BufferedWriter(new OutputStreamWriter(out,
configuration.docencoding));
}
try {
String line;
while ((line = reader.readLine()) != null) {
writer.write(line);
writer.write(DocletConstants.NL);
}
} finally {
reader.close();
writer.close();
}
}
} finally {
in.close();
out.close();
}
} catch (IOException e) {
e.printStackTrace(System.err);
throw new DocletAbortException(e);
}
}
/** Return true if the file can be read. */
public abstract boolean canRead();
/** Return true if the file can be written. */
public abstract boolean canWrite();
/** Return true if the file exists. */
public abstract boolean exists();
/** Return the base name (last component) of the file name. */
public abstract String getName();
/** Return the file system path for this file. */
public abstract String getPath();
/** Return true if file has an absolute path name. */
public abstract boolean isAbsolute();
/** Return true if file identifies a directory. */
public abstract boolean isDirectory();
/** Return true if file identifies a file. */
public abstract boolean isFile();
/** Return true if this file is the same as another. */
public abstract boolean isSameFile(DocFile other);
/** If the file is a directory, list its contents. */
public abstract Iterable<DocFile> list() throws IOException;
/** Create the file as a directory, including any parent directories. */
public abstract boolean mkdirs();
/**
* Derive a new file by resolving a relative path against this file.
* The new file will inherit the configuration and location of this file
* If this file has a path set, the new file will have a corresponding
* new path.
*/
public abstract DocFile resolve(DocPath p);
/**
* Derive a new file by resolving a relative path against this file.
* The new file will inherit the configuration and location of this file
* If this file has a path set, the new file will have a corresponding
* new path.
*/
public abstract DocFile resolve(String p);
/**
* Resolve a relative file against the given output location.
* @param locn Currently, only
* {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} is supported.
*/
public abstract DocFile resolveAgainst(Location locn);
}

100
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/DocFileFactory.java Normal file
View File

@@ -0,0 +1,100 @@
/*
* Copyright (c) 1998, 2012, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.util.Map;
import java.util.WeakHashMap;
import javax.tools.JavaFileManager;
import javax.tools.JavaFileManager.Location;
import javax.tools.StandardJavaFileManager;
import javax.tools.StandardLocation;
import com.sun.tools.doclets.internal.toolkit.Configuration;
/**
* Factory for DocFile objects.
*
* <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>
*
* @since 1.8
*/
abstract class DocFileFactory {
private static final Map<Configuration, DocFileFactory> factories =
new WeakHashMap<Configuration, DocFileFactory>();
/**
* Get the appropriate factory, based on the file manager given in the
* configuration.
*/
static synchronized DocFileFactory getFactory(Configuration configuration) {
DocFileFactory f = factories.get(configuration);
if (f == null) {
JavaFileManager fm = configuration.getFileManager();
if (fm instanceof StandardJavaFileManager)
f = new StandardDocFileFactory(configuration);
else {
try {
Class<?> pathFileManagerClass =
Class.forName("com.sun.tools.javac.nio.PathFileManager");
if (pathFileManagerClass.isAssignableFrom(fm.getClass()))
f = new PathDocFileFactory(configuration);
} catch (Throwable t) {
throw new IllegalStateException(t);
}
}
factories.put(configuration, f);
}
return f;
}
protected Configuration configuration;
protected DocFileFactory(Configuration configuration) {
this.configuration = configuration;
}
/** Create a DocFile for a directory. */
abstract DocFile createFileForDirectory(String file);
/** Create a DocFile for a file that will be opened for reading. */
abstract DocFile createFileForInput(String file);
/** Create a DocFile for a file that will be opened for writing. */
abstract DocFile createFileForOutput(DocPath path);
/**
* List the directories and files found in subdirectories along the
* elements of the given location.
* @param location currently, only {@link StandardLocation#SOURCE_PATH} is supported.
* @param path the subdirectory of the directories of the location for which to
* list files
*/
abstract Iterable<DocFile> list(Location location, DocPath path);
}

244
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/DocFinder.java Normal file
View File

@@ -0,0 +1,244 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.taglets.*;
/**
* Search for the requested documentation. Inherit documentation if necessary.
*
* <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
* @since 1.5
*/
public class DocFinder {
/**
* The class that encapsulates the input.
*/
public static class Input {
/**
* The element to search documentation from.
*/
public ProgramElementDoc element;
/**
* The taglet to search for documentation on behalf of. Null if we want
* to search for overall documentation.
*/
public InheritableTaglet taglet = null;
/**
* The id of the tag to retrieve documentation for.
*/
public String tagId = null;
/**
* The tag to retrieve documentation for. This is only used for the
* inheritDoc tag.
*/
public Tag tag = null;
/**
* True if we only want to search for the first sentence.
*/
public boolean isFirstSentence = false;
/**
* True if we are looking for documentation to replace the inheritDocTag.
*/
public boolean isInheritDocTag = false;
/**
* Used to distinguish between type variable param tags and regular
* param tags.
*/
public boolean isTypeVariableParamTag = false;
public Input(ProgramElementDoc element, InheritableTaglet taglet, Tag tag,
boolean isFirstSentence, boolean isInheritDocTag) {
this(element);
this.taglet = taglet;
this.tag = tag;
this.isFirstSentence = isFirstSentence;
this.isInheritDocTag = isInheritDocTag;
}
public Input(ProgramElementDoc element, InheritableTaglet taglet, String tagId) {
this(element);
this.taglet = taglet;
this.tagId = tagId;
}
public Input(ProgramElementDoc element, InheritableTaglet taglet, String tagId,
boolean isTypeVariableParamTag) {
this(element);
this.taglet = taglet;
this.tagId = tagId;
this.isTypeVariableParamTag = isTypeVariableParamTag;
}
public Input(ProgramElementDoc element, InheritableTaglet taglet) {
this(element);
this.taglet = taglet;
}
public Input(ProgramElementDoc element) {
if (element == null)
throw new NullPointerException();
this.element = element;
}
public Input(ProgramElementDoc element, boolean isFirstSentence) {
this(element);
this.isFirstSentence = isFirstSentence;
}
public Input copy() {
Input clone = new Input(this.element);
clone.taglet = this.taglet;
clone.tagId = this.tagId;
clone.tag = this.tag;
clone.isFirstSentence = this.isFirstSentence;
clone.isInheritDocTag = this.isInheritDocTag;
clone.isTypeVariableParamTag = this.isTypeVariableParamTag;
if (clone.element == null)
throw new NullPointerException();
return clone;
}
}
/**
* The class that encapsulates the output.
*/
public static class Output {
/**
* The tag that holds the documentation. Null if documentation
* is not held by a tag.
*/
public Tag holderTag;
/**
* The Doc object that holds the documentation.
*/
public Doc holder;
/**
* The inherited documentation.
*/
public Tag[] inlineTags = new Tag[] {};
/**
* False if documentation could not be inherited.
*/
public boolean isValidInheritDocTag = true;
/**
* When automatically inheriting throws tags, you sometime must inherit
* more than one tag. For example if the element declares that it throws
* IOException and the overridden element has throws tags for IOException and
* ZipException, both tags would be inherited because ZipException is a
* subclass of IOException. This subclass of DocFinder.Output allows
* multiple tag inheritence.
*/
public List<Tag> tagList = new ArrayList<Tag>();
}
/**
* Search for the requested comments in the given element. If it does not
* have comments, return documentation from the overriden element if possible.
* If the overriden element does not exist or does not have documentation to
* inherit, search for documentation to inherit from implemented methods.
*
* @param input the input object used to perform the search.
*
* @return an Output object representing the documentation that was found.
*/
public static Output search(Input input) {
Output output = new Output();
if (input.isInheritDocTag) {
//Do nothing because "element" does not have any documentation.
//All it has it {@inheritDoc}.
} else if (input.taglet == null) {
//We want overall documentation.
output.inlineTags = input.isFirstSentence ?
input.element.firstSentenceTags() :
input.element.inlineTags();
output.holder = input.element;
} else {
input.taglet.inherit(input, output);
}
if (output.inlineTags != null && output.inlineTags.length > 0) {
return output;
}
output.isValidInheritDocTag = false;
Input inheritedSearchInput = input.copy();
inheritedSearchInput.isInheritDocTag = false;
if (input.element instanceof MethodDoc) {
MethodDoc overriddenMethod = ((MethodDoc) input.element).overriddenMethod();
if (overriddenMethod != null) {
inheritedSearchInput.element = overriddenMethod;
output = search(inheritedSearchInput);
output.isValidInheritDocTag = true;
if (output.inlineTags.length > 0) {
return output;
}
}
//NOTE: When we fix the bug where ClassDoc.interfaceTypes() does
// not pass all implemented interfaces, we will use the
// appropriate element here.
MethodDoc[] implementedMethods =
(new ImplementedMethods((MethodDoc) input.element, null)).build(false);
for (int i = 0; i < implementedMethods.length; i++) {
inheritedSearchInput.element = implementedMethods[i];
output = search(inheritedSearchInput);
output.isValidInheritDocTag = true;
if (output.inlineTags.length > 0) {
return output;
}
}
} else if (input.element instanceof ClassDoc) {
ProgramElementDoc superclass = ((ClassDoc) input.element).superclass();
if (superclass != null) {
inheritedSearchInput.element = superclass;
output = search(inheritedSearchInput);
output.isValidInheritDocTag = true;
if (output.inlineTags.length > 0) {
return output;
}
}
}
return output;
}
}

97
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/DocLink.java Normal file
View File

@@ -0,0 +1,97 @@
/*
* Copyright (c) 2012, 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 com.sun.tools.doclets.internal.toolkit.util;
/**
* Abstraction for simple relative URIs, consisting of a path,
* an optional query, and an optional fragment. DocLink objects can
* be created by the constructors below or from a DocPath using the
* convenience methods, {@link DocPath#fragment fragment} and
* {@link DocPath#query query}.
*
* <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 DocLink {
final String path;
final String query;
final String fragment;
/** Create a DocLink representing the URI {@code #fragment}. */
public static DocLink fragment(String fragment) {
return new DocLink((String) null, (String) null, fragment);
}
/** Create a DocLink representing the URI {@code path}. */
public DocLink(DocPath path) {
this(path.getPath(), null, null);
}
/**
* Create a DocLink representing the URI {@code path?query#fragment}.
* query and fragment may be null.
*/
public DocLink(DocPath path, String query, String fragment) {
this(path.getPath(), query, fragment);
}
/**
* Create a DocLink representing the URI {@code path?query#fragment}.
* Any of the component parts may be null.
*/
public DocLink(String path, String query, String fragment) {
this.path = path;
this.query = query;
this.fragment = fragment;
}
/**
* Return the link in the form "path?query#fragment", omitting any empty
* components.
*/
@Override
public String toString() {
// common fast path
if (path != null && isEmpty(query) && isEmpty(fragment))
return path;
StringBuilder sb = new StringBuilder();
if (path != null)
sb.append(path);
if (!isEmpty(query))
sb.append("?").append(query);
if (!isEmpty(fragment))
sb.append("#").append(fragment);
return sb.toString();
}
private static boolean isEmpty(String s) {
return (s == null) || s.isEmpty();
}
}

191
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/DocPath.java Normal file
View File

@@ -0,0 +1,191 @@
/*
* Copyright (c) 1998, 2012, 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 com.sun.tools.doclets.internal.toolkit.util;
import com.sun.javadoc.ClassDoc;
import com.sun.javadoc.PackageDoc;
/**
* Abstraction for immutable relative paths.
* Paths always use '/' as a separator, and never begin or end with '/'.
*
* <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 DocPath {
private final String path;
/** The empty path. */
public static final DocPath empty = new DocPath("");
/** The empty path. */
public static final DocPath parent = new DocPath("..");
/**
* Create a path from a string.
*/
public static DocPath create(String p) {
return (p == null) || p.isEmpty() ? empty : new DocPath(p);
}
/**
* Return the path for a class.
* For example, if the class is java.lang.Object,
* the path is java/lang/Object.html.
*/
public static DocPath forClass(ClassDoc cd) {
return (cd == null) ? empty :
forPackage(cd.containingPackage()).resolve(forName(cd));
}
/**
* Return the path for the simple name of the class.
* For example, if the class is java.lang.Object,
* the path is Object.html.
*/
public static DocPath forName(ClassDoc cd) {
return (cd == null) ? empty : new DocPath(cd.name() + ".html");
}
/**
* Return the path for the package of a class.
* For example, if the class is java.lang.Object,
* the path is java/lang.
*/
public static DocPath forPackage(ClassDoc cd) {
return (cd == null) ? empty : forPackage(cd.containingPackage());
}
/**
* Return the path for a package.
* For example, if the package is java.lang,
* the path is java/lang.
*/
public static DocPath forPackage(PackageDoc pd) {
return (pd == null) ? empty : DocPath.create(pd.name().replace('.', '/'));
}
/**
* Return the inverse path for a package.
* For example, if the package is java.lang,
* the inverse path is ../...
*/
public static DocPath forRoot(PackageDoc pd) {
String name = (pd == null) ? "" : pd.name();
if (name.isEmpty())
return empty;
return new DocPath(name.replace('.', '/').replaceAll("[^/]+", ".."));
}
/**
* Return the relative path from one package to another.
*/
public static DocPath relativePath(PackageDoc from, PackageDoc to) {
return forRoot(from).resolve(forPackage(to));
}
protected DocPath(String p) {
path = (p.endsWith("/") ? p.substring(0, p.length() - 1) : p);
}
/** {@inheritDoc} */
@Override
public boolean equals(Object other) {
return (other instanceof DocPath) && path.equals(((DocPath)other).path);
}
/** {@inheritDoc} */
@Override
public int hashCode() {
return path.hashCode();
}
public DocPath basename() {
int sep = path.lastIndexOf("/");
return (sep == -1) ? this : new DocPath(path.substring(sep + 1));
}
public DocPath parent() {
int sep = path.lastIndexOf("/");
return (sep == -1) ? empty : new DocPath(path.substring(0, sep));
}
/**
* Return the path formed by appending the specified string to the current path.
*/
public DocPath resolve(String p) {
if (p == null || p.isEmpty())
return this;
if (path.isEmpty())
return new DocPath(p);
return new DocPath(path + "/" + p);
}
/**
* Return the path by appending the specified path to the current path.
*/
public DocPath resolve(DocPath p) {
if (p == null || p.isEmpty())
return this;
if (path.isEmpty())
return p;
return new DocPath(path + "/" + p.getPath());
}
/**
* Return the inverse path for this path.
* For example, if the path is a/b/c, the inverse path is ../../..
*/
public DocPath invert() {
return new DocPath(path.replaceAll("[^/]+", ".."));
}
/**
* Return true if this path is empty.
*/
public boolean isEmpty() {
return path.isEmpty();
}
public DocLink fragment(String fragment) {
return new DocLink(path, null, fragment);
}
public DocLink query(String query) {
return new DocLink(path, query, null);
}
/**
* Return this path as a string.
*/
// This is provided instead of using toString() to help catch
// unintended use of toString() in string concatenation sequences.
public String getPath() {
return path;
}
}

139
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/DocPaths.java Normal file
View File

@@ -0,0 +1,139 @@
/*
* Copyright (c) 1998, 2013, 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 com.sun.tools.doclets.internal.toolkit.util;
/**
* Standard DocPath objects.
*
* <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>
*
* @since 8
*/
public class DocPaths {
/** The name of the file for all classes, using frames. */
public static final DocPath ALLCLASSES_FRAME = DocPath.create("allclasses-frame.html");
/** The name of the file for all classes, without using frames. */
public static final DocPath ALLCLASSES_NOFRAME = DocPath.create("allclasses-noframe.html");
/** The name of the sub-directory for storing class usage info. */
public static final DocPath CLASS_USE = DocPath.create("class-use");
/** The name of the file for constant values. */
public static final DocPath CONSTANT_VALUES = DocPath.create("constant-values.html");
/** The name of the fie for deprecated elements. */
public static final DocPath DEPRECATED_LIST = DocPath.create("deprecated-list.html");
/** The name of the subdirectory for user-provided additional documentation files. */
public static final DocPath DOC_FILES = DocPath.create("doc-files");
/** The name of the file for help info. */
public static final DocPath HELP_DOC = DocPath.create("help-doc.html");
/** The name of the main index file. */
public static final DocPath INDEX = DocPath.create("index.html");
/** The name of the single index file for all classes. */
public static final DocPath INDEX_ALL = DocPath.create("index-all.html");
/** The name of the directory for the split index files. */
public static final DocPath INDEX_FILES = DocPath.create("index-files");
/** Generate the name of one of the files in the split index. */
public static final DocPath indexN(int n) {
return DocPath.create("index-" + n + ".html");
}
/** The name of the default javascript file. */
public static final DocPath JAVASCRIPT = DocPath.create("script.js");
/** The name of the file for the overview frame. */
public static final DocPath OVERVIEW_FRAME = DocPath.create("overview-frame.html");
/** The name of the file for the overview summary. */
public static final DocPath OVERVIEW_SUMMARY = DocPath.create("overview-summary.html");
/** The name of the file for the overview tree. */
public static final DocPath OVERVIEW_TREE = DocPath.create("overview-tree.html");
/** The name of the file for the package frame. */
public static final DocPath PACKAGE_FRAME = DocPath.create("package-frame.html");
/** The name of the file for the profile frame. */
public static final DocPath profileFrame(String profileName) {
return DocPath.create(profileName + "-frame.html");
}
/** The name of the file for the profile package frame. */
public static final DocPath profilePackageFrame(String profileName) {
return DocPath.create(profileName + "-package-frame.html");
}
/** The name of the file for the profile package summary. */
public static final DocPath profilePackageSummary(String profileName) {
return DocPath.create(profileName + "-package-summary.html");
}
/** The name of the file for the profile summary. */
public static final DocPath profileSummary(String profileName) {
return DocPath.create(profileName + "-summary.html");
}
/** The name of the file for the package list. */
public static final DocPath PACKAGE_LIST = DocPath.create("package-list");
/** The name of the file for the package summary. */
public static final DocPath PACKAGE_SUMMARY = DocPath.create("package-summary.html");
/** The name of the file for the package tree. */
public static final DocPath PACKAGE_TREE = DocPath.create("package-tree.html");
/** The name of the file for the package usage info. */
public static final DocPath PACKAGE_USE = DocPath.create("package-use.html");
/** The name of the file for the overview frame. */
public static final DocPath PROFILE_OVERVIEW_FRAME = DocPath.create("profile-overview-frame.html");
/** The name of the sub-package from which resources are read. */
public static final DocPath RESOURCES = DocPath.create("resources");
/** The name of the file for the serialized form info. */
public static final DocPath SERIALIZED_FORM = DocPath.create("serialized-form.html");
/** The name of the directory in which HTML versions of the source code
* are generated.
*/
public static final DocPath SOURCE_OUTPUT = DocPath.create("src-html");
/** The name of the default stylesheet. */
public static final DocPath STYLESHEET = DocPath.create("stylesheet.css");
}

44
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/DocletAbortException.java Normal file
View File

@@ -0,0 +1,44 @@
/*
* Copyright (c) 1997, 2013, 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 com.sun.tools.doclets.internal.toolkit.util;
/**
* <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 DocletAbortException extends RuntimeException {
private static final long serialVersionUID = -9131058909576418984L;
public DocletAbortException(String message) {
super(message);
}
public DocletAbortException(Throwable cause) {
super(cause);
}
}

61
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/DocletConstants.java Normal file
View File

@@ -0,0 +1,61 @@
/*
* Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.util;
/**
* Stores all constants for a Doclet. Extend this class if you have doclet
* specific constants to add.
*
* <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
* @since 1.5
*/
public class DocletConstants {
/**
* The default amount of space between tab stops.
*/
public static final int DEFAULT_TAB_STOP_LENGTH = 8;
/**
* The line separator for the current operating system.
*/
public static final String NL = System.getProperty("line.separator");
/**
* The default package name.
*/
public static final String DEFAULT_PACKAGE_NAME = "<Unnamed>";
/**
* The default package file name.
*/
public static final String DEFAULT_PACKAGE_FILE_NAME = "default";
}

316
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/Extern.java Normal file
View File

@@ -0,0 +1,316 @@
/*
* Copyright (c) 1998, 2014, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.io.*;
import java.net.*;
import java.util.HashMap;
import java.util.Map;
import javax.tools.DocumentationTool;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
/**
* Process and manage "-link" and "-linkoffline" to external packages. The
* options "-link" and "-linkoffline" both depend on the fact that Javadoc now
* generates "package-list"(lists all the packages which are getting
* documented) file in the current or the destination directory, while
* generating the documentation.
*
* <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 Atul M Dambalkar
* @author Robert Field
*/
public class Extern {
/**
* Map package names onto Extern Item objects.
* Lazily initialized.
*/
private Map<String,Item> packageToItemMap;
/**
* The global configuration information for this run.
*/
private final Configuration configuration;
/**
* True if we are using -linkoffline and false if -link is used instead.
*/
private boolean linkoffline = false;
/**
* Stores the info for one external doc set
*/
private class Item {
/**
* Package name, found in the "package-list" file in the {@link path}.
*/
final String packageName;
/**
* The URL or the directory path at which the package documentation will be
* avaliable.
*/
final String path;
/**
* If given path is directory path then true else if it is a URL then false.
*/
final boolean relative;
/**
* Constructor to build a Extern Item object and map it with the package name.
* If the same package name is found in the map, then the first mapped
* Item object or offline location will be retained.
*
* @param packageName Package name found in the "package-list" file.
* @param path URL or Directory path from where the "package-list"
* file is picked.
* @param relative True if path is URL, false if directory path.
*/
Item(String packageName, String path, boolean relative) {
this.packageName = packageName;
this.path = path;
this.relative = relative;
if (packageToItemMap == null) {
packageToItemMap = new HashMap<String,Item>();
}
if (!packageToItemMap.containsKey(packageName)) { // save the previous
packageToItemMap.put(packageName, this); // mapped location
}
}
/**
* String representation of "this" with packagename and the path.
*/
public String toString() {
return packageName + (relative? " -> " : " => ") + path;
}
}
public Extern(Configuration configuration) {
this.configuration = configuration;
}
/**
* Determine if a doc item is externally documented.
*
* @param doc A ProgramElementDoc.
*/
public boolean isExternal(ProgramElementDoc doc) {
if (packageToItemMap == null) {
return false;
}
return packageToItemMap.get(doc.containingPackage().name()) != null;
}
/**
* Convert a link to be an external link if appropriate.
*
* @param pkgName The package name.
* @param relativepath The relative path.
* @param filename The link to convert.
* @return if external return converted link else return null
*/
public DocLink getExternalLink(String pkgName,
DocPath relativepath, String filename) {
return getExternalLink(pkgName, relativepath, filename, null);
}
public DocLink getExternalLink(String pkgName,
DocPath relativepath, String filename, String memberName) {
Item fnd = findPackageItem(pkgName);
if (fnd == null)
return null;
DocPath p = fnd.relative ?
relativepath.resolve(fnd.path).resolve(filename) :
DocPath.create(fnd.path).resolve(filename);
return new DocLink(p, "is-external=true", memberName);
}
/**
* Build the extern package list from given URL or the directory path.
* Flag error if the "-link" or "-linkoffline" option is already used.
*
* @param url URL or Directory path.
* @param pkglisturl This can be another URL for "package-list" or ordinary
* file.
* @param reporter The <code>DocErrorReporter</code> used to report errors.
* @param linkoffline True if -linkoffline is used and false if -link is used.
*/
public boolean link(String url, String pkglisturl,
DocErrorReporter reporter, boolean linkoffline) {
this.linkoffline = linkoffline;
try {
url = adjustEndFileSeparator(url);
if (isUrl(pkglisturl)) {
readPackageListFromURL(url, toURL(adjustEndFileSeparator(pkglisturl)));
} else {
readPackageListFromFile(url, DocFile.createFileForInput(configuration, pkglisturl));
}
return true;
} catch (Fault f) {
reporter.printWarning(f.getMessage());
return false;
}
}
private URL toURL(String url) throws Fault {
try {
return new URL(url);
} catch (MalformedURLException e) {
throw new Fault(configuration.getText("doclet.MalformedURL", url), e);
}
}
private class Fault extends Exception {
private static final long serialVersionUID = 0;
Fault(String msg, Exception cause) {
super(msg, cause);
}
}
/**
* Get the Extern Item object associated with this package name.
*
* @param pkgName Package name.
*/
private Item findPackageItem(String pkgName) {
if (packageToItemMap == null) {
return null;
}
return packageToItemMap.get(pkgName);
}
/**
* If the URL or Directory path is missing end file separator, add that.
*/
private String adjustEndFileSeparator(String url) {
return url.endsWith("/") ? url : url + '/';
}
/**
* Fetch the URL and read the "package-list" file.
*
* @param urlpath Path to the packages.
* @param pkglisturlpath URL or the path to the "package-list" file.
*/
private void readPackageListFromURL(String urlpath, URL pkglisturlpath)
throws Fault {
try {
URL link = pkglisturlpath.toURI().resolve(DocPaths.PACKAGE_LIST.getPath()).toURL();
readPackageList(link.openStream(), urlpath, false);
} catch (URISyntaxException exc) {
throw new Fault(configuration.getText("doclet.MalformedURL", pkglisturlpath.toString()), exc);
} catch (MalformedURLException exc) {
throw new Fault(configuration.getText("doclet.MalformedURL", pkglisturlpath.toString()), exc);
} catch (IOException exc) {
throw new Fault(configuration.getText("doclet.URL_error", pkglisturlpath.toString()), exc);
}
}
/**
* Read the "package-list" file which is available locally.
*
* @param path URL or directory path to the packages.
* @param pkgListPath Path to the local "package-list" file.
*/
private void readPackageListFromFile(String path, DocFile pkgListPath)
throws Fault {
DocFile file = pkgListPath.resolve(DocPaths.PACKAGE_LIST);
if (! (file.isAbsolute() || linkoffline)){
file = file.resolveAgainst(DocumentationTool.Location.DOCUMENTATION_OUTPUT);
}
try {
if (file.exists() && file.canRead()) {
boolean pathIsRelative =
!DocFile.createFileForInput(configuration, path).isAbsolute()
&& !isUrl(path);
readPackageList(file.openInputStream(), path, pathIsRelative);
} else {
throw new Fault(configuration.getText("doclet.File_error", file.getPath()), null);
}
} catch (IOException exc) {
throw new Fault(configuration.getText("doclet.File_error", file.getPath()), exc);
}
}
/**
* Read the file "package-list" and for each package name found, create
* Extern object and associate it with the package name in the map.
*
* @param input InputStream from the "package-list" file.
* @param path URL or the directory path to the packages.
* @param relative Is path relative?
*/
private void readPackageList(InputStream input, String path,
boolean relative)
throws IOException {
BufferedReader in = new BufferedReader(new InputStreamReader(input));
StringBuilder strbuf = new StringBuilder();
try {
int c;
while ((c = in.read()) >= 0) {
char ch = (char)c;
if (ch == '\n' || ch == '\r') {
if (strbuf.length() > 0) {
String packname = strbuf.toString();
String packpath = path +
packname.replace('.', '/') + '/';
new Item(packname, packpath, relative);
strbuf.setLength(0);
}
} else {
strbuf.append(ch);
}
}
} finally {
input.close();
}
}
public boolean isUrl (String urlCandidate) {
try {
new URL(urlCandidate);
//No exception was thrown, so this must really be a URL.
return true;
} catch (MalformedURLException e) {
//Since exception is thrown, this must be a directory path.
return false;
}
}
}

39
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/FatalError.java Normal file
View File

@@ -0,0 +1,39 @@
/*
* 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 com.sun.tools.doclets.internal.toolkit.util;
/**
* <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>
*/
@Deprecated
public class FatalError extends Error {
private static final long serialVersionUID = -9131058909576418984L;
public FatalError() { }
}

247
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/Group.java Normal file
View File

@@ -0,0 +1,247 @@
/*
* Copyright (c) 1998, 2012, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
/**
* Process and manage grouping of packages, as specified by "-group" option on
* the command line.
* <p>
* For example, if user has used -group option as
* -group "Core Packages" "java.*" -group "CORBA Packages" "org.omg.*", then
* the packages specified on the command line will be grouped according to their
* names starting with either "java." or "org.omg.". All the other packages
* which do not fall in the user given groups, are grouped in default group,
* named as either "Other Packages" or "Packages" depending upon if "-group"
* option used or not at all used respectively.
* </p>
* <p>
* Also the packages are grouped according to the longest possible match of
* their names with the grouping information provided. For example, if there
* are two groups, like -group "Lang" "java.lang" and -group "Core" "java.*",
* will put the package java.lang in the group "Lang" and not in group "Core".
* </p>
*
* <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 Atul M Dambalkar
*/
public class Group {
/**
* Map of regular expressions with the corresponding group name.
*/
private Map<String,String> regExpGroupMap = new HashMap<String,String>();
/**
* List of regular expressions sorted according to the length. Regular
* expression with longest length will be first in the sorted order.
*/
private List<String> sortedRegExpList = new ArrayList<String>();
/**
* List of group names in the same order as given on the command line.
*/
private List<String> groupList = new ArrayList<String>();
/**
* Map of non-regular expressions(possible package names) with the
* corresponding group name.
*/
private Map<String,String> pkgNameGroupMap = new HashMap<String,String>();
/**
* The global configuration information for this run.
*/
private final Configuration configuration;
/**
* Since we need to sort the keys in the reverse order(longest key first),
* the compare method in the implementing class is doing the reverse
* comparison.
*/
private static class MapKeyComparator implements Comparator<String> {
public int compare(String key1, String key2) {
return key2.length() - key1.length();
}
}
public Group(Configuration configuration) {
this.configuration = configuration;
}
/**
* Depending upon the format of the package name provided in the "-group"
* option, generate two separate maps. There will be a map for mapping
* regular expression(only meta character allowed is '*' and that is at the
* end of the regular expression) on to the group name. And another map
* for mapping (possible) package names(if the name format doesen't contain
* meta character '*', then it is assumed to be a package name) on to the
* group name. This will also sort all the regular expressions found in the
* reverse order of their lengths, i.e. longest regular expression will be
* first in the sorted list.
*
* @param groupname The name of the group from -group option.
* @param pkgNameFormList List of the package name formats.
*/
public boolean checkPackageGroups(String groupname,
String pkgNameFormList) {
StringTokenizer strtok = new StringTokenizer(pkgNameFormList, ":");
if (groupList.contains(groupname)) {
configuration.message.warning("doclet.Groupname_already_used", groupname);
return false;
}
groupList.add(groupname);
while (strtok.hasMoreTokens()) {
String id = strtok.nextToken();
if (id.length() == 0) {
configuration.message.warning("doclet.Error_in_packagelist", groupname, pkgNameFormList);
return false;
}
if (id.endsWith("*")) {
id = id.substring(0, id.length() - 1);
if (foundGroupFormat(regExpGroupMap, id)) {
return false;
}
regExpGroupMap.put(id, groupname);
sortedRegExpList.add(id);
} else {
if (foundGroupFormat(pkgNameGroupMap, id)) {
return false;
}
pkgNameGroupMap.put(id, groupname);
}
}
Collections.sort(sortedRegExpList, new MapKeyComparator());
return true;
}
/**
* Search if the given map has given the package format.
*
* @param map Map to be searched.
* @param pkgFormat The pacakge format to search.
*
* @return true if package name format found in the map, else false.
*/
boolean foundGroupFormat(Map<String,?> map, String pkgFormat) {
if (map.containsKey(pkgFormat)) {
configuration.message.error("doclet.Same_package_name_used", pkgFormat);
return true;
}
return false;
}
/**
* Group the packages according the grouping information provided on the
* command line. Given a list of packages, search each package name in
* regular expression map as well as package name map to get the
* corresponding group name. Create another map with mapping of group name
* to the package list, which will fall under the specified group. If any
* package doesen't belong to any specified group on the comamnd line, then
* a new group named "Other Packages" will be created for it. If there are
* no groups found, in other words if "-group" option is not at all used,
* then all the packages will be grouped under group "Packages".
*
* @param packages Packages specified on the command line.
*/
public Map<String,List<PackageDoc>> groupPackages(PackageDoc[] packages) {
Map<String,List<PackageDoc>> groupPackageMap = new HashMap<String,List<PackageDoc>>();
String defaultGroupName =
(pkgNameGroupMap.isEmpty() && regExpGroupMap.isEmpty())?
configuration.message.getText("doclet.Packages") :
configuration.message.getText("doclet.Other_Packages");
// if the user has not used the default group name, add it
if (!groupList.contains(defaultGroupName)) {
groupList.add(defaultGroupName);
}
for (int i = 0; i < packages.length; i++) {
PackageDoc pkg = packages[i];
String pkgName = pkg.name();
String groupName = pkgNameGroupMap.get(pkgName);
// if this package is not explicitly assigned to a group,
// try matching it to group specified by regular expression
if (groupName == null) {
groupName = regExpGroupName(pkgName);
}
// if it is in neither group map, put it in the default
// group
if (groupName == null) {
groupName = defaultGroupName;
}
getPkgList(groupPackageMap, groupName).add(pkg);
}
return groupPackageMap;
}
/**
* Search for package name in the sorted regular expression
* list, if found return the group name. If not, return null.
*
* @param pkgName Name of package to be found in the regular
* expression list.
*/
String regExpGroupName(String pkgName) {
for (int j = 0; j < sortedRegExpList.size(); j++) {
String regexp = sortedRegExpList.get(j);
if (pkgName.startsWith(regexp)) {
return regExpGroupMap.get(regexp);
}
}
return null;
}
/**
* For the given group name, return the package list, on which it is mapped.
* Create a new list, if not found.
*
* @param map Map to be searched for gorup name.
* @param groupname Group name to search.
*/
List<PackageDoc> getPkgList(Map<String,List<PackageDoc>> map, String groupname) {
List<PackageDoc> list = map.get(groupname);
if (list == null) {
list = new ArrayList<PackageDoc>();
map.put(groupname, list);
}
return list;
}
/**
* Return the list of groups, in the same order as specified
* on the command line.
*/
public List<String> getGroupList() {
return groupList;
}
}

151
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/ImplementedMethods.java Normal file
View File

@@ -0,0 +1,151 @@
/*
* Copyright (c) 1999, 2012, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.Configuration;
/**
* For a given class method, build an array of interface methods which it
* implements.
*
* <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 Atul M Dambalkar
*/
public class ImplementedMethods {
private Map<MethodDoc,Type> interfaces = new HashMap<MethodDoc,Type>();
private List<MethodDoc> methlist = new ArrayList<MethodDoc>();
private Configuration configuration;
private final ClassDoc classdoc;
private final MethodDoc method;
public ImplementedMethods(MethodDoc method, Configuration configuration) {
this.method = method;
this.configuration = configuration;
classdoc = method.containingClass();
}
/**
* Return the array of interface methods which the method passed in the
* constructor is implementing. The search/build order is as follows:
* <pre>
* 1. Search in all the immediate interfaces which this method's class is
* implementing. Do it recursively for the superinterfaces as well.
* 2. Traverse all the superclasses and search recursively in the
* interfaces which those superclasses implement.
*</pre>
*
* @return MethodDoc[] Array of implemented methods.
*/
public MethodDoc[] build(boolean sort) {
buildImplementedMethodList(sort);
return methlist.toArray(new MethodDoc[methlist.size()]);
}
public MethodDoc[] build() {
return build(true);
}
public Type getMethodHolder(MethodDoc methodDoc) {
return interfaces.get(methodDoc);
}
/**
* Search for the method in the array of interfaces. If found check if it is
* overridden by any other subinterface method which this class
* implements. If it is not overidden, add it in the method list.
* Do this recursively for all the extended interfaces for each interface
* from the array passed.
*/
private void buildImplementedMethodList(boolean sort) {
List<Type> intfacs = Util.getAllInterfaces(classdoc, configuration, sort);
for (Iterator<Type> iter = intfacs.iterator(); iter.hasNext(); ) {
Type interfaceType = iter.next();
MethodDoc found = Util.findMethod(interfaceType.asClassDoc(), method);
if (found != null) {
removeOverriddenMethod(found);
if (!overridingMethodFound(found)) {
methlist.add(found);
interfaces.put(found, interfaceType);
}
}
}
}
/**
* Search in the method list and check if it contains a method which
* is overridden by the method as parameter. If found, remove the
* overridden method from the method list.
*
* @param method Is this method overriding a method in the method list.
*/
private void removeOverriddenMethod(MethodDoc method) {
ClassDoc overriddenClass = method.overriddenClass();
if (overriddenClass != null) {
for (int i = 0; i < methlist.size(); i++) {
ClassDoc cd = methlist.get(i).containingClass();
if (cd == overriddenClass || overriddenClass.subclassOf(cd)) {
methlist.remove(i); // remove overridden method
return;
}
}
}
}
/**
* Search in the already found methods' list and check if it contains
* a method which is overriding the method parameter or is the method
* parameter itself.
*
* @param method MethodDoc Method to be searched in the Method List for
* an overriding method.
*/
private boolean overridingMethodFound(MethodDoc method) {
ClassDoc containingClass = method.containingClass();
for (int i = 0; i < methlist.size(); i++) {
MethodDoc listmethod = methlist.get(i);
if (containingClass == listmethod.containingClass()) {
// it's the same method.
return true;
}
ClassDoc cd = listmethod.overriddenClass();
if (cd == null) {
continue;
}
if (cd == containingClass || cd.subclassOf(containingClass)) {
return true;
}
}
return false;
}
}

262
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/IndexBuilder.java Normal file
View File

@@ -0,0 +1,262 @@
/*
* Copyright (c) 1998, 2013, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
/**
* Build the mapping of each Unicode character with it's member lists
* containing members names starting with it. Also build a list for all the
* Unicode characters which start a member name. Member name is
* classkind or field or method or constructor name.
*
* <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>
*
* @since 1.2
* @see java.lang.Character
* @author Atul M Dambalkar
*/
public class IndexBuilder {
/**
* Mapping of each Unicode Character with the member list containing
* members with names starting with it.
*/
private Map<Character,List<Doc>> indexmap = new HashMap<Character,List<Doc>>();
/**
* Don't generate deprecated information if true.
*/
private boolean noDeprecated;
/**
* Build this Index only for classes?
*/
private boolean classesOnly;
/**
* Indicates javafx mode.
*/
private boolean javafx;
// make ProgramElementDoc[] when new toArray is available
protected final Object[] elements;
/**
* A comparator used to sort classes and members.
* Note: Maybe this compare code belongs in the tool?
*/
private class DocComparator implements Comparator<Doc> {
public int compare(Doc d1, Doc d2) {
String doc1 = d1.name();
String doc2 = d2.name();
int compareResult;
if ((compareResult = doc1.compareToIgnoreCase(doc2)) != 0) {
return compareResult;
} else if (d1 instanceof ProgramElementDoc && d2 instanceof ProgramElementDoc) {
doc1 = (((ProgramElementDoc) d1).qualifiedName());
doc2 = (((ProgramElementDoc) d2).qualifiedName());
return doc1.compareToIgnoreCase(doc2);
} else {
return 0;
}
}
}
/**
* Constructor. Build the index map.
*
* @param configuration the current configuration of the doclet.
* @param noDeprecated true if -nodeprecated option is used,
* false otherwise.
*/
public IndexBuilder(Configuration configuration, boolean noDeprecated) {
this(configuration, noDeprecated, false);
}
/**
* Constructor. Build the index map.
*
* @param configuration the current configuration of the doclet.
* @param noDeprecated true if -nodeprecated option is used,
* false otherwise.
* @param classesOnly Include only classes in index.
*/
public IndexBuilder(Configuration configuration, boolean noDeprecated,
boolean classesOnly) {
if (classesOnly) {
configuration.message.notice("doclet.Building_Index_For_All_Classes");
} else {
configuration.message.notice("doclet.Building_Index");
}
this.noDeprecated = noDeprecated;
this.classesOnly = classesOnly;
this.javafx = configuration.javafx;
buildIndexMap(configuration.root);
Set<Character> set = indexmap.keySet();
elements = set.toArray();
Arrays.sort(elements);
}
/**
* Sort the index map. Traverse the index map for all it's elements and
* sort each element which is a list.
*/
protected void sortIndexMap() {
for (Iterator<List<Doc>> it = indexmap.values().iterator(); it.hasNext(); ) {
Collections.sort(it.next(), new DocComparator());
}
}
/**
* Get all the members in all the Packages and all the Classes
* given on the command line. Form separate list of those members depending
* upon their names.
*
* @param root Root of the documemt.
*/
protected void buildIndexMap(RootDoc root) {
PackageDoc[] packages = root.specifiedPackages();
ClassDoc[] classes = root.classes();
if (!classesOnly) {
if (packages.length == 0) {
Set<PackageDoc> set = new HashSet<PackageDoc>();
PackageDoc pd;
for (int i = 0; i < classes.length; i++) {
pd = classes[i].containingPackage();
if (pd != null && pd.name().length() > 0) {
set.add(pd);
}
}
adjustIndexMap(set.toArray(packages));
} else {
adjustIndexMap(packages);
}
}
adjustIndexMap(classes);
if (!classesOnly) {
for (int i = 0; i < classes.length; i++) {
if (shouldAddToIndexMap(classes[i])) {
putMembersInIndexMap(classes[i]);
}
}
}
sortIndexMap();
}
/**
* Put all the members(fields, methods and constructors) in the classdoc
* to the indexmap.
*
* @param classdoc ClassDoc whose members will be added to the indexmap.
*/
protected void putMembersInIndexMap(ClassDoc classdoc) {
adjustIndexMap(classdoc.fields());
adjustIndexMap(classdoc.methods());
adjustIndexMap(classdoc.constructors());
}
/**
* Adjust list of members according to their names. Check the first
* character in a member name, and then add the member to a list of members
* for that particular unicode character.
*
* @param elements Array of members.
*/
protected void adjustIndexMap(Doc[] elements) {
for (int i = 0; i < elements.length; i++) {
if (shouldAddToIndexMap(elements[i])) {
String name = elements[i].name();
char ch = (name.length()==0)?
'*' :
Character.toUpperCase(name.charAt(0));
Character unicode = new Character(ch);
List<Doc> list = indexmap.get(unicode);
if (list == null) {
list = new ArrayList<Doc>();
indexmap.put(unicode, list);
}
list.add(elements[i]);
}
}
}
/**
* Should this doc element be added to the index map?
*/
protected boolean shouldAddToIndexMap(Doc element) {
if (javafx) {
if (element.tags("treatAsPrivate").length > 0) {
return false;
}
}
if (element instanceof PackageDoc)
// Do not add to index map if -nodeprecated option is set and the
// package is marked as deprecated.
return !(noDeprecated && Util.isDeprecated(element));
else
// Do not add to index map if -nodeprecated option is set and if the
// Doc is marked as deprecated or the containing package is marked as
// deprecated.
return !(noDeprecated &&
(Util.isDeprecated(element) ||
Util.isDeprecated(((ProgramElementDoc)element).containingPackage())));
}
/**
* Return a map of all the individual member lists with Unicode character.
*
* @return Map index map.
*/
public Map<Character,List<Doc>> getIndexMap() {
return indexmap;
}
/**
* Return the sorted list of members, for passed Unicode Character.
*
* @param index index Unicode character.
* @return List member list for specific Unicode character.
*/
public List<Doc> getMemberList(Character index) {
return indexmap.get(index);
}
/**
* Array of IndexMap keys, Unicode characters.
*/
public Object[] elements() {
return elements;
}
}

226
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/MessageRetriever.java Normal file
View File

@@ -0,0 +1,226 @@
/*
* Copyright (c) 1998, 2013, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.text.MessageFormat;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.Configuration;
/**
* Retrieve and format messages stored in a resource.
*
* <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>
*
* @since 1.2
* @author Atul M Dambalkar
* @author Robert Field
*/
public class MessageRetriever {
/**
* The global configuration information for this run.
*/
private final Configuration configuration;
/**
* The location from which to lazily fetch the resource..
*/
private final String resourcelocation;
/**
* The lazily fetched resource..
*/
private ResourceBundle messageRB;
/**
* Initialize the ResourceBundle with the given resource.
*
* @param rb the resource bundle to read.
*/
public MessageRetriever(ResourceBundle rb) {
this.configuration = null;
this.messageRB = rb;
this.resourcelocation = null;
}
/**
* Initialize the ResourceBundle with the given resource.
*
* @param configuration the configuration
* @param resourcelocation Resource.
*/
public MessageRetriever(Configuration configuration,
String resourcelocation) {
this.configuration = configuration;
this.resourcelocation = resourcelocation;
}
/**
* Get and format message string from resource
*
* @param key selects message from resource
* @param args arguments to be replaced in the message.
* @throws MissingResourceException when the key does not
* exist in the properties file.
*/
public String getText(String key, Object... args) throws MissingResourceException {
if (messageRB == null) {
try {
messageRB = ResourceBundle.getBundle(resourcelocation);
} catch (MissingResourceException e) {
throw new Error("Fatal: Resource (" + resourcelocation +
") for javadoc doclets is missing.");
}
}
String message = messageRB.getString(key);
return MessageFormat.format(message, args);
}
/**
* Print error message, increment error count.
*
* @param pos the position of the source
* @param msg message to print
*/
private void printError(SourcePosition pos, String msg) {
configuration.root.printError(pos, msg);
}
/**
* Print error message, increment error count.
*
* @param msg message to print
*/
private void printError(String msg) {
configuration.root.printError(msg);
}
/**
* Print warning message, increment warning count.
*
* @param pos the position of the source
* @param msg message to print
*/
private void printWarning(SourcePosition pos, String msg) {
configuration.root.printWarning(pos, msg);
}
/**
* Print warning message, increment warning count.
*
* @param msg message to print
*/
private void printWarning(String msg) {
configuration.root.printWarning(msg);
}
/**
* Print a message.
*
* @param pos the position of the source
* @param msg message to print
*/
private void printNotice(SourcePosition pos, String msg) {
configuration.root.printNotice(pos, msg);
}
/**
* Print a message.
*
* @param msg message to print
*/
private void printNotice(String msg) {
configuration.root.printNotice(msg);
}
/**
* Print error message, increment error count.
*
* @param pos the position of the source
* @param key selects message from resource
* @param args arguments to be replaced in the message.
*/
public void error(SourcePosition pos, String key, Object... args) {
printError(pos, getText(key, args));
}
/**
* Print error message, increment error count.
*
* @param key selects message from resource
* @param args arguments to be replaced in the message.
*/
public void error(String key, Object... args) {
printError(getText(key, args));
}
/**
* Print warning message, increment warning count.
*
* @param pos the position of the source
* @param key selects message from resource
* @param args arguments to be replaced in the message.
*/
public void warning(SourcePosition pos, String key, Object... args) {
if (configuration.showMessage(pos, key))
printWarning(pos, getText(key, args));
}
/**
* Print warning message, increment warning count.
*
* @param key selects message from resource
* @param args arguments to be replaced in the message.
*/
public void warning(String key, Object... args) {
printWarning(getText(key, args));
}
/**
* Print a message.
*
* @param pos the position of the source
* @param key selects message from resource
* @param args arguments to be replaced in the message.
*/
public void notice(SourcePosition pos, String key, Object... args) {
printNotice(pos, getText(key, args));
}
/**
* Print a message.
*
* @param key selects message from resource
* @param args arguments to be replaced in the message.
*/
public void notice(String key, Object... args) {
printNotice(getText(key, args));
}
}

159
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/MetaKeywords.java Normal file
View File

@@ -0,0 +1,159 @@
/*
* Copyright (c) 2002, 2013, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.javac.jvm.Profile;
import com.sun.tools.doclets.internal.toolkit.*;
/**
* Provides methods for creating an array of class, method and
* field names to be included as meta keywords in the HTML header
* of class pages. These keywords improve search results
* on browsers that look for keywords.
*
* <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 Doug Kramer
*/
public class MetaKeywords {
/**
* The global configuration information for this run.
*/
private final Configuration configuration;
/**
* Constructor
*/
public MetaKeywords(Configuration configuration) {
this.configuration = configuration;
}
/**
* Returns an array of strings where each element
* is a class, method or field name. This array is
* used to create one meta keyword tag for each element.
* Method parameter lists are converted to "()" and
* overloads are combined.
*
* Constructors are not included because they have the same
* name as the class, which is already included.
* Nested class members are not included because their
* definitions are on separate pages.
*/
public String[] getMetaKeywords(ClassDoc classdoc) {
ArrayList<String> results = new ArrayList<String>();
// Add field and method keywords only if -keywords option is used
if( configuration.keywords ) {
results.addAll(getClassKeyword(classdoc));
results.addAll(getMemberKeywords(classdoc.fields()));
results.addAll(getMemberKeywords(classdoc.methods()));
}
return results.toArray(new String[]{});
}
/**
* Get the current class for a meta tag keyword, as the first
* and only element of an array list.
*/
protected ArrayList<String> getClassKeyword(ClassDoc classdoc) {
String cltypelower = classdoc.isInterface() ? "interface" : "class";
ArrayList<String> metakeywords = new ArrayList<String>(1);
metakeywords.add(classdoc.qualifiedName() + " " + cltypelower);
return metakeywords;
}
/**
* Get the package keywords.
*/
public String[] getMetaKeywords(PackageDoc packageDoc) {
if( configuration.keywords ) {
String pkgName = Util.getPackageName(packageDoc);
return new String[] { pkgName + " " + "package" };
} else {
return new String[] {};
}
}
/**
* Get the profile keywords.
*
* @param profile the profile being documented
*/
public String[] getMetaKeywords(Profile profile) {
if( configuration.keywords ) {
String profileName = profile.name;
return new String[] { profileName + " " + "profile" };
} else {
return new String[] {};
}
}
/**
* Get the overview keywords.
*/
public String[] getOverviewMetaKeywords(String title, String docTitle) {
if( configuration.keywords ) {
String windowOverview = configuration.getText(title);
String[] metakeywords = { windowOverview };
if (docTitle.length() > 0 ) {
metakeywords[0] += ", " + docTitle;
}
return metakeywords;
} else {
return new String[] {};
}
}
/**
* Get members for meta tag keywords as an array,
* where each member name is a string element of the array.
* The parameter lists are not included in the keywords;
* therefore all overloaded methods are combined.<br>
* Example: getValue(Object) is returned in array as getValue()
*
* @param memberdocs array of MemberDoc objects to be added to keywords
*/
protected ArrayList<String> getMemberKeywords(MemberDoc[] memberdocs) {
ArrayList<String> results = new ArrayList<String>();
String membername;
for (int i=0; i < memberdocs.length; i++) {
membername = memberdocs[i].name()
+ (memberdocs[i].isMethod() ? "()" : "");
if ( ! results.contains(membername) ) {
results.add(membername);
}
}
return results;
}
}

72
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/MethodFinder.java Normal file
View File

@@ -0,0 +1,72 @@
/*
* Copyright (c) 1999, 2012, 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 com.sun.tools.doclets.internal.toolkit.util;
import com.sun.javadoc.*;
/**
* This class is useful for searching a method which has documentation
* comment and documentation tags. The method is searched in all the
* superclasses and interfaces(subsequently super-interfaces also)
* recursively.
*
* <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 abstract class MethodFinder {
abstract boolean isCorrectMethod(MethodDoc method);
public MethodDoc search(ClassDoc cd, MethodDoc method) {
MethodDoc meth = searchInterfaces(cd, method);
if (meth != null) {
return meth;
}
ClassDoc icd = cd.superclass();
if (icd != null) {
meth = Util.findMethod(icd, method);
if (meth != null) {
if (isCorrectMethod(meth)) {
return meth;
}
}
return search(icd, method);
}
return null;
}
public MethodDoc searchInterfaces(ClassDoc cd, MethodDoc method) {
MethodDoc[] implementedMethods = (new ImplementedMethods(method, null)).build();
for (int i = 0; i < implementedMethods.length; i++) {
if (isCorrectMethod(implementedMethods[i])) {
return implementedMethods[i];
}
}
return null;
}
}

69
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/MethodTypes.java Normal file
View File

@@ -0,0 +1,69 @@
/*
* Copyright (c) 2012, 2015, 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 com.sun.tools.doclets.internal.toolkit.util;
/**
* Enum representing method types.
*
* @author Bhavesh Patel
*/
public enum MethodTypes {
ALL(0xffff, "doclet.All_Methods", "t0", true),
STATIC(0x1, "doclet.Static_Methods", "t1", false),
INSTANCE(0x2, "doclet.Instance_Methods", "t2", false),
ABSTRACT(0x4, "doclet.Abstract_Methods", "t3", false),
CONCRETE(0x8, "doclet.Concrete_Methods", "t4", false),
DEFAULT(0x10, "doclet.Default_Methods", "t5", false),
DEPRECATED(0x20, "doclet.Deprecated_Methods", "t6", false);
private final int value;
private final String resourceKey;
private final String tabId;
private final boolean isDefaultTab;
MethodTypes(int v, String k, String id, boolean dt) {
this.value = v;
this.resourceKey = k;
this.tabId = id;
this.isDefaultTab = dt;
}
public int value() {
return value;
}
public String resourceKey() {
return resourceKey;
}
public String tabId() {
return tabId;
}
public boolean isDefaultTab() {
return isDefaultTab;
}
}

92
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/PackageListWriter.java Normal file
View File

@@ -0,0 +1,92 @@
/*
* Copyright (c) 1998, 2013, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.io.*;
import java.util.*;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
/**
* Write out the package index.
*
* <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>
*
* @see com.sun.javadoc.PackageDoc
* @author Atul M Dambalkar
*/
public class PackageListWriter extends PrintWriter {
private Configuration configuration;
/**
* Constructor.
*
* @param configuration the current configuration of the doclet.
*/
public PackageListWriter(Configuration configuration) throws IOException {
super(DocFile.createFileForOutput(configuration, DocPaths.PACKAGE_LIST).openWriter());
this.configuration = configuration;
}
/**
* Generate the package index.
*
* @param configuration the current configuration of the doclet.
* @throws DocletAbortException
*/
public static void generate(Configuration configuration) {
PackageListWriter packgen;
try {
packgen = new PackageListWriter(configuration);
packgen.generatePackageListFile(configuration.root);
packgen.close();
} catch (IOException exc) {
configuration.message.error("doclet.exception_encountered",
exc.toString(), DocPaths.PACKAGE_LIST);
throw new DocletAbortException(exc);
}
}
protected void generatePackageListFile(RootDoc root) {
PackageDoc[] packages = configuration.packages;
ArrayList<String> names = new ArrayList<String>();
for (int i = 0; i < packages.length; i++) {
// if the -nodeprecated option is set and the package is marked as
// deprecated, do not include it in the packages list.
if (!(configuration.nodeprecated && Util.isDeprecated(packages[i])))
names.add(packages[i].name());
}
Collections.sort(names);
for (int i = 0; i < names.size(); i++) {
println(names.get(i));
}
}
}

320
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/PathDocFileFactory.java Normal file
View File

@@ -0,0 +1,320 @@
/*
* Copyright (c) 1998, 2013, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.io.BufferedInputStream;
import java.io.BufferedOutputStream;
import java.io.BufferedWriter;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.UnsupportedEncodingException;
import java.io.Writer;
import java.nio.file.DirectoryStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Set;
import javax.tools.DocumentationTool;
import javax.tools.FileObject;
import javax.tools.JavaFileManager.Location;
import javax.tools.JavaFileObject;
import javax.tools.StandardLocation;
import com.sun.tools.doclets.internal.toolkit.Configuration;
import com.sun.tools.javac.nio.PathFileManager;
/**
* Implementation of DocFileFactory using a {@link PathFileManager}.
*
* <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>
*
* @since 1.8
*/
class PathDocFileFactory extends DocFileFactory {
private final PathFileManager fileManager;
private final Path destDir;
public PathDocFileFactory(Configuration configuration) {
super(configuration);
fileManager = (PathFileManager) configuration.getFileManager();
if (!configuration.destDirName.isEmpty()
|| !fileManager.hasLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT)) {
try {
String dirName = configuration.destDirName.isEmpty() ? "." : configuration.destDirName;
Path dir = fileManager.getDefaultFileSystem().getPath(dirName);
fileManager.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(dir));
} catch (IOException e) {
throw new DocletAbortException(e);
}
}
destDir = fileManager.getLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT).iterator().next();
}
public DocFile createFileForDirectory(String file) {
return new StandardDocFile(fileManager.getDefaultFileSystem().getPath(file));
}
public DocFile createFileForInput(String file) {
return new StandardDocFile(fileManager.getDefaultFileSystem().getPath(file));
}
public DocFile createFileForOutput(DocPath path) {
return new StandardDocFile(DocumentationTool.Location.DOCUMENTATION_OUTPUT, path);
}
@Override
Iterable<DocFile> list(Location location, DocPath path) {
if (location != StandardLocation.SOURCE_PATH)
throw new IllegalArgumentException();
Set<DocFile> files = new LinkedHashSet<DocFile>();
if (fileManager.hasLocation(location)) {
for (Path f: fileManager.getLocation(location)) {
if (Files.isDirectory(f)) {
f = f.resolve(path.getPath());
if (Files.exists(f))
files.add(new StandardDocFile(f));
}
}
}
return files;
}
class StandardDocFile extends DocFile {
private Path file;
/** Create a StandardDocFile for a given file. */
private StandardDocFile(Path file) {
super(configuration);
this.file = file;
}
/** Create a StandardDocFile for a given location and relative path. */
private StandardDocFile(Location location, DocPath path) {
super(configuration, location, path);
this.file = destDir.resolve(path.getPath());
}
/** Open an input stream for the file. */
public InputStream openInputStream() throws IOException {
JavaFileObject fo = getJavaFileObjectForInput(file);
return new BufferedInputStream(fo.openInputStream());
}
/**
* Open an output stream for the file.
* The file must have been created with a location of
* {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} and a corresponding relative path.
*/
public OutputStream openOutputStream() throws IOException, UnsupportedEncodingException {
if (location != DocumentationTool.Location.DOCUMENTATION_OUTPUT)
throw new IllegalStateException();
OutputStream out = getFileObjectForOutput(path).openOutputStream();
return new BufferedOutputStream(out);
}
/**
* Open an writer for the file, using the encoding (if any) given in the
* doclet configuration.
* The file must have been created with a location of
* {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} and a corresponding relative path.
*/
public Writer openWriter() throws IOException, UnsupportedEncodingException {
if (location != DocumentationTool.Location.DOCUMENTATION_OUTPUT)
throw new IllegalStateException();
OutputStream out = getFileObjectForOutput(path).openOutputStream();
if (configuration.docencoding == null) {
return new BufferedWriter(new OutputStreamWriter(out));
} else {
return new BufferedWriter(new OutputStreamWriter(out, configuration.docencoding));
}
}
/** Return true if the file can be read. */
public boolean canRead() {
return Files.isReadable(file);
}
/** Return true if the file can be written. */
public boolean canWrite() {
return Files.isWritable(file);
}
/** Return true if the file exists. */
public boolean exists() {
return Files.exists(file);
}
/** Return the base name (last component) of the file name. */
public String getName() {
return file.getFileName().toString();
}
/** Return the file system path for this file. */
public String getPath() {
return file.toString();
}
/** Return true is file has an absolute path name. */
public boolean isAbsolute() {
return file.isAbsolute();
}
/** Return true is file identifies a directory. */
public boolean isDirectory() {
return Files.isDirectory(file);
}
/** Return true is file identifies a file. */
public boolean isFile() {
return Files.isRegularFile(file);
}
/** Return true if this file is the same as another. */
public boolean isSameFile(DocFile other) {
if (!(other instanceof StandardDocFile))
return false;
try {
return Files.isSameFile(file, ((StandardDocFile) other).file);
} catch (IOException e) {
return false;
}
}
/** If the file is a directory, list its contents. */
public Iterable<DocFile> list() throws IOException {
List<DocFile> files = new ArrayList<DocFile>();
try (DirectoryStream<Path> ds = Files.newDirectoryStream(file)) {
for (Path f: ds) {
files.add(new StandardDocFile(f));
}
}
return files;
}
/** Create the file as a directory, including any parent directories. */
public boolean mkdirs() {
try {
Files.createDirectories(file);
return true;
} catch (IOException e) {
return false;
}
}
/**
* Derive a new file by resolving a relative path against this file.
* The new file will inherit the configuration and location of this file
* If this file has a path set, the new file will have a corresponding
* new path.
*/
public DocFile resolve(DocPath p) {
return resolve(p.getPath());
}
/**
* Derive a new file by resolving a relative path against this file.
* The new file will inherit the configuration and location of this file
* If this file has a path set, the new file will have a corresponding
* new path.
*/
public DocFile resolve(String p) {
if (location == null && path == null) {
return new StandardDocFile(file.resolve(p));
} else {
return new StandardDocFile(location, path.resolve(p));
}
}
/**
* Resolve a relative file against the given output location.
* @param locn Currently, only
* {@link DocumentationTool.Location.DOCUMENTATION_OUTPUT} is supported.
*/
public DocFile resolveAgainst(Location locn) {
if (locn != DocumentationTool.Location.DOCUMENTATION_OUTPUT)
throw new IllegalArgumentException();
return new StandardDocFile(destDir.resolve(file));
}
/** Return a string to identify the contents of this object,
* for debugging purposes.
*/
@Override
public String toString() {
StringBuilder sb = new StringBuilder();
sb.append("PathDocFile[");
if (location != null)
sb.append("locn:").append(location).append(",");
if (path != null)
sb.append("path:").append(path.getPath()).append(",");
sb.append("file:").append(file);
sb.append("]");
return sb.toString();
}
private JavaFileObject getJavaFileObjectForInput(Path file) {
return fileManager.getJavaFileObjects(file).iterator().next();
}
private FileObject getFileObjectForOutput(DocPath path) throws IOException {
// break the path into a package-part and the rest, by finding
// the position of the last '/' before an invalid character for a
// package name, such as the "." before an extension or the "-"
// in filenames like package-summary.html, doc-files or src-html.
String p = path.getPath();
int lastSep = -1;
for (int i = 0; i < p.length(); i++) {
char ch = p.charAt(i);
if (ch == '/') {
lastSep = i;
} else if (i == lastSep + 1 && !Character.isJavaIdentifierStart(ch)
|| !Character.isJavaIdentifierPart(ch)) {
break;
}
}
String pkg = (lastSep == -1) ? "" : p.substring(0, lastSep);
String rest = p.substring(lastSep + 1);
return fileManager.getFileForOutput(location, pkg, rest, null);
}
}
}

292
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/SimpleDocFileFactory.java Normal file
View File

@@ -0,0 +1,292 @@
/*
* Copyright (c) 1998, 2013, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.io.BufferedInputStream;
import java.io.BufferedOutputStream;
import java.io.BufferedWriter;
import java.io.File;
import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.UnsupportedEncodingException;
import java.io.Writer;
import java.util.ArrayList;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Set;
import javax.tools.DocumentationTool;
import javax.tools.JavaFileManager.Location;
import javax.tools.StandardLocation;
import com.sun.tools.doclets.internal.toolkit.Configuration;
/**
* Implementation of DocFileFactory that just uses java.io.File API,
* and does not use a JavaFileManager..
*
* <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>
*
* @since 1.8
*/
class SimpleDocFileFactory extends DocFileFactory {
public SimpleDocFileFactory(Configuration configuration) {
super(configuration);
}
public DocFile createFileForDirectory(String file) {
return new SimpleDocFile(new File(file));
}
public DocFile createFileForInput(String file) {
return new SimpleDocFile(new File(file));
}
public DocFile createFileForOutput(DocPath path) {
return new SimpleDocFile(DocumentationTool.Location.DOCUMENTATION_OUTPUT, path);
}
@Override
Iterable<DocFile> list(Location location, DocPath path) {
if (location != StandardLocation.SOURCE_PATH)
throw new IllegalArgumentException();
Set<DocFile> files = new LinkedHashSet<DocFile>();
for (String s : configuration.sourcepath.split(File.pathSeparator)) {
if (s.isEmpty())
continue;
File f = new File(s);
if (f.isDirectory()) {
f = new File(f, path.getPath());
if (f.exists())
files.add(new SimpleDocFile(f));
}
}
return files;
}
class SimpleDocFile extends DocFile {
private File file;
/** Create a DocFile for a given file. */
private SimpleDocFile(File file) {
super(configuration);
this.file = file;
}
/** Create a DocFile for a given location and relative path. */
private SimpleDocFile(Location location, DocPath path) {
super(configuration, location, path);
String destDirName = configuration.destDirName;
this.file = destDirName.isEmpty() ? new File(path.getPath())
: new File(destDirName, path.getPath());
}
/** Open an input stream for the file. */
public InputStream openInputStream() throws FileNotFoundException {
return new BufferedInputStream(new FileInputStream(file));
}
/**
* Open an output stream for the file.
* The file must have been created with a location of
* {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} and a corresponding relative path.
*/
public OutputStream openOutputStream() throws IOException, UnsupportedEncodingException {
if (location != DocumentationTool.Location.DOCUMENTATION_OUTPUT)
throw new IllegalStateException();
createDirectoryForFile(file);
return new BufferedOutputStream(new FileOutputStream(file));
}
/**
* Open an writer for the file, using the encoding (if any) given in the
* doclet configuration.
* The file must have been created with a location of
* {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} and a corresponding relative path.
*/
public Writer openWriter() throws IOException, UnsupportedEncodingException {
if (location != DocumentationTool.Location.DOCUMENTATION_OUTPUT)
throw new IllegalStateException();
createDirectoryForFile(file);
FileOutputStream fos = new FileOutputStream(file);
if (configuration.docencoding == null) {
return new BufferedWriter(new OutputStreamWriter(fos));
} else {
return new BufferedWriter(new OutputStreamWriter(fos, configuration.docencoding));
}
}
/** Return true if the file can be read. */
public boolean canRead() {
return file.canRead();
}
/** Return true if the file can be written. */
public boolean canWrite() {
return file.canRead();
}
/** Return true if the file exists. */
public boolean exists() {
return file.exists();
}
/** Return the base name (last component) of the file name. */
public String getName() {
return file.getName();
}
/** Return the file system path for this file. */
public String getPath() {
return file.getPath();
}
/** Return true is file has an absolute path name. */
public boolean isAbsolute() {
return file.isAbsolute();
}
/** Return true is file identifies a directory. */
public boolean isDirectory() {
return file.isDirectory();
}
/** Return true is file identifies a file. */
public boolean isFile() {
return file.isFile();
}
/** Return true if this file is the same as another. */
public boolean isSameFile(DocFile other) {
if (!(other instanceof SimpleDocFile))
return false;
try {
return file.exists()
&& file.getCanonicalFile().equals(((SimpleDocFile)other).file.getCanonicalFile());
} catch (IOException e) {
return false;
}
}
/** If the file is a directory, list its contents. */
public Iterable<DocFile> list() {
List<DocFile> files = new ArrayList<DocFile>();
for (File f: file.listFiles()) {
files.add(new SimpleDocFile(f));
}
return files;
}
/** Create the file as a directory, including any parent directories. */
public boolean mkdirs() {
return file.mkdirs();
}
/**
* Derive a new file by resolving a relative path against this file.
* The new file will inherit the configuration and location of this file
* If this file has a path set, the new file will have a corresponding
* new path.
*/
public DocFile resolve(DocPath p) {
return resolve(p.getPath());
}
/**
* Derive a new file by resolving a relative path against this file.
* The new file will inherit the configuration and location of this file
* If this file has a path set, the new file will have a corresponding
* new path.
*/
public DocFile resolve(String p) {
if (location == null && path == null) {
return new SimpleDocFile(new File(file, p));
} else {
return new SimpleDocFile(location, path.resolve(p));
}
}
/**
* Resolve a relative file against the given output location.
* @param locn Currently, only
* {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} is supported.
*/
public DocFile resolveAgainst(Location locn) {
if (locn != DocumentationTool.Location.DOCUMENTATION_OUTPUT)
throw new IllegalArgumentException();
return new SimpleDocFile(
new File(configuration.destDirName, file.getPath()));
}
/**
* Given a path string create all the directories in the path. For example,
* if the path string is "java/applet", the method will create directory
* "java" and then "java/applet" if they don't exist. The file separator
* string "/" is platform dependent system property.
*
* @param path Directory path string.
*/
private void createDirectoryForFile(File file) {
File dir = file.getParentFile();
if (dir == null || dir.exists() || dir.mkdirs())
return;
configuration.message.error(
"doclet.Unable_to_create_directory_0", dir.getPath());
throw new DocletAbortException("can't create directory");
}
/** Return a string to identify the contents of this object,
* for debugging purposes.
*/
@Override
public String toString() {
StringBuilder sb = new StringBuilder();
sb.append("DocFile[");
if (location != null)
sb.append("locn:").append(location).append(",");
if (path != null)
sb.append("path:").append(path.getPath()).append(",");
sb.append("file:").append(file);
sb.append("]");
return sb.toString();
}
}
}

322
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/StandardDocFileFactory.java Normal file
View File

@@ -0,0 +1,322 @@
/*
* Copyright (c) 1998, 2013, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.io.BufferedInputStream;
import java.io.BufferedOutputStream;
import java.io.BufferedWriter;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.UnsupportedEncodingException;
import java.io.Writer;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Set;
import javax.tools.DocumentationTool;
import javax.tools.FileObject;
import javax.tools.JavaFileManager.Location;
import javax.tools.JavaFileObject;
import javax.tools.StandardJavaFileManager;
import javax.tools.StandardLocation;
import com.sun.tools.doclets.internal.toolkit.Configuration;
import com.sun.tools.javac.util.Assert;
/**
* Implementation of DocFileFactory using a {@link StandardJavaFileManager}.
*
* <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>
*
* @since 1.8
*/
class StandardDocFileFactory extends DocFileFactory {
private final StandardJavaFileManager fileManager;
private File destDir;
public StandardDocFileFactory(Configuration configuration) {
super(configuration);
fileManager = (StandardJavaFileManager) configuration.getFileManager();
}
private File getDestDir() {
if (destDir == null) {
if (!configuration.destDirName.isEmpty()
|| !fileManager.hasLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT)) {
try {
String dirName = configuration.destDirName.isEmpty() ? "." : configuration.destDirName;
File dir = new File(dirName);
fileManager.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(dir));
} catch (IOException e) {
throw new DocletAbortException(e);
}
}
destDir = fileManager.getLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT).iterator().next();
}
return destDir;
}
public DocFile createFileForDirectory(String file) {
return new StandardDocFile(new File(file));
}
public DocFile createFileForInput(String file) {
return new StandardDocFile(new File(file));
}
public DocFile createFileForOutput(DocPath path) {
return new StandardDocFile(DocumentationTool.Location.DOCUMENTATION_OUTPUT, path);
}
@Override
Iterable<DocFile> list(Location location, DocPath path) {
if (location != StandardLocation.SOURCE_PATH)
throw new IllegalArgumentException();
Set<DocFile> files = new LinkedHashSet<DocFile>();
Location l = fileManager.hasLocation(StandardLocation.SOURCE_PATH)
? StandardLocation.SOURCE_PATH : StandardLocation.CLASS_PATH;
for (File f: fileManager.getLocation(l)) {
if (f.isDirectory()) {
f = new File(f, path.getPath());
if (f.exists())
files.add(new StandardDocFile(f));
}
}
return files;
}
private static File newFile(File dir, String path) {
return (dir == null) ? new File(path) : new File(dir, path);
}
class StandardDocFile extends DocFile {
private File file;
/** Create a StandardDocFile for a given file. */
private StandardDocFile(File file) {
super(configuration);
this.file = file;
}
/** Create a StandardDocFile for a given location and relative path. */
private StandardDocFile(Location location, DocPath path) {
super(configuration, location, path);
Assert.check(location == DocumentationTool.Location.DOCUMENTATION_OUTPUT);
this.file = newFile(getDestDir(), path.getPath());
}
/** Open an input stream for the file. */
public InputStream openInputStream() throws IOException {
JavaFileObject fo = getJavaFileObjectForInput(file);
return new BufferedInputStream(fo.openInputStream());
}
/**
* Open an output stream for the file.
* The file must have been created with a location of
* {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} and a corresponding relative path.
*/
public OutputStream openOutputStream() throws IOException, UnsupportedEncodingException {
if (location != DocumentationTool.Location.DOCUMENTATION_OUTPUT)
throw new IllegalStateException();
OutputStream out = getFileObjectForOutput(path).openOutputStream();
return new BufferedOutputStream(out);
}
/**
* Open an writer for the file, using the encoding (if any) given in the
* doclet configuration.
* The file must have been created with a location of
* {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} and a corresponding relative path.
*/
public Writer openWriter() throws IOException, UnsupportedEncodingException {
if (location != DocumentationTool.Location.DOCUMENTATION_OUTPUT)
throw new IllegalStateException();
OutputStream out = getFileObjectForOutput(path).openOutputStream();
if (configuration.docencoding == null) {
return new BufferedWriter(new OutputStreamWriter(out));
} else {
return new BufferedWriter(new OutputStreamWriter(out, configuration.docencoding));
}
}
/** Return true if the file can be read. */
public boolean canRead() {
return file.canRead();
}
/** Return true if the file can be written. */
public boolean canWrite() {
return file.canWrite();
}
/** Return true if the file exists. */
public boolean exists() {
return file.exists();
}
/** Return the base name (last component) of the file name. */
public String getName() {
return file.getName();
}
/** Return the file system path for this file. */
public String getPath() {
return file.getPath();
}
/** Return true is file has an absolute path name. */
public boolean isAbsolute() {
return file.isAbsolute();
}
/** Return true is file identifies a directory. */
public boolean isDirectory() {
return file.isDirectory();
}
/** Return true is file identifies a file. */
public boolean isFile() {
return file.isFile();
}
/** Return true if this file is the same as another. */
public boolean isSameFile(DocFile other) {
if (!(other instanceof StandardDocFile))
return false;
try {
return file.exists()
&& file.getCanonicalFile().equals(((StandardDocFile) other).file.getCanonicalFile());
} catch (IOException e) {
return false;
}
}
/** If the file is a directory, list its contents. */
public Iterable<DocFile> list() {
List<DocFile> files = new ArrayList<DocFile>();
for (File f: file.listFiles()) {
files.add(new StandardDocFile(f));
}
return files;
}
/** Create the file as a directory, including any parent directories. */
public boolean mkdirs() {
return file.mkdirs();
}
/**
* Derive a new file by resolving a relative path against this file.
* The new file will inherit the configuration and location of this file
* If this file has a path set, the new file will have a corresponding
* new path.
*/
public DocFile resolve(DocPath p) {
return resolve(p.getPath());
}
/**
* Derive a new file by resolving a relative path against this file.
* The new file will inherit the configuration and location of this file
* If this file has a path set, the new file will have a corresponding
* new path.
*/
public DocFile resolve(String p) {
if (location == null && path == null) {
return new StandardDocFile(new File(file, p));
} else {
return new StandardDocFile(location, path.resolve(p));
}
}
/**
* Resolve a relative file against the given output location.
* @param locn Currently, only
* {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} is supported.
*/
public DocFile resolveAgainst(Location locn) {
if (locn != DocumentationTool.Location.DOCUMENTATION_OUTPUT)
throw new IllegalArgumentException();
return new StandardDocFile(newFile(getDestDir(), file.getPath()));
}
/** Return a string to identify the contents of this object,
* for debugging purposes.
*/
@Override
public String toString() {
StringBuilder sb = new StringBuilder();
sb.append("StandardDocFile[");
if (location != null)
sb.append("locn:").append(location).append(",");
if (path != null)
sb.append("path:").append(path.getPath()).append(",");
sb.append("file:").append(file);
sb.append("]");
return sb.toString();
}
private JavaFileObject getJavaFileObjectForInput(File file) {
return fileManager.getJavaFileObjects(file).iterator().next();
}
private FileObject getFileObjectForOutput(DocPath path) throws IOException {
// break the path into a package-part and the rest, by finding
// the position of the last '/' before an invalid character for a
// package name, such as the "." before an extension or the "-"
// in filenames like package-summary.html, doc-files or src-html.
String p = path.getPath();
int lastSep = -1;
for (int i = 0; i < p.length(); i++) {
char ch = p.charAt(i);
if (ch == '/') {
lastSep = i;
} else if (i == lastSep + 1 && !Character.isJavaIdentifierStart(ch)
|| !Character.isJavaIdentifierPart(ch)) {
break;
}
}
String pkg = (lastSep == -1) ? "" : p.substring(0, lastSep);
String rest = p.substring(lastSep + 1);
return fileManager.getFileForOutput(location, pkg, rest, null);
}
}
}

45
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/TaggedMethodFinder.java Normal file
View File

@@ -0,0 +1,45 @@
/*
* Copyright (c) 1999, 2012, 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 com.sun.tools.doclets.internal.toolkit.util;
import com.sun.javadoc.*;
/**
* Find a tagged method.
*
* <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 Atul M Dambalkar
*/
public class TaggedMethodFinder extends MethodFinder {
public boolean isCorrectMethod(MethodDoc method) {
return method.paramTags().length + method.tags("return").length +
method.throwsTags().length + method.seeTags().length > 0;
}
}

110
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/TextTag.java Normal file
View File

@@ -0,0 +1,110 @@
/*
* Copyright (c) 2003, 2012, 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 com.sun.tools.doclets.internal.toolkit.util;
import com.sun.javadoc.*;
/**
* A tag that holds nothing but plain text. This is useful for passing
* text to methods that only accept inline tags as a parameter.
*
* <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
* @since 1.5
*/
public class TextTag implements Tag {
protected final String text;
protected final String name = "Text";
protected final Doc holder;
/**
* Constructor
*/
public TextTag(Doc holder, String text) {
super();
this.holder = holder;
this.text = text;
}
/**
* {@inheritDoc}
*/
public String name() {
return name;
}
/**
* {@inheritDoc}
*/
public Doc holder() {
return holder;
}
/**
* {@inheritDoc}
*/
public String kind() {
return name;
}
/**
* {@inheritDoc}
*/
public String text() {
return text;
}
/**
* {@inheritDoc}
*/
public String toString() {
return name + ":" + text;
}
/**
* {@inheritDoc}
*/
public Tag[] inlineTags() {
return new Tag[] {this};
}
/**
* {@inheritDoc}
*/
public Tag[] firstSentenceTags() {
return new Tag[] {this};
}
/**
* {@inheritDoc}
*/
public SourcePosition position() {
return holder.position();
}
}

792
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/Util.java Normal file
View File

@@ -0,0 +1,792 @@
/*
* Copyright (c) 1999, 2013, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.io.*;
import java.lang.annotation.ElementType;
import java.util.*;
import javax.tools.StandardLocation;
import com.sun.javadoc.*;
import com.sun.javadoc.AnnotationDesc.ElementValuePair;
import com.sun.tools.doclets.internal.toolkit.*;
import com.sun.tools.javac.util.StringUtils;
/**
* Utilities Class for Doclets.
*
* <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 Atul M Dambalkar
* @author Jamie Ho
*/
public class Util {
/**
* Return array of class members whose documentation is to be generated.
* If the member is deprecated do not include such a member in the
* returned array.
*
* @param members Array of members to choose from.
* @return ProgramElementDoc[] Array of eligible members for whom
* documentation is getting generated.
*/
public static ProgramElementDoc[] excludeDeprecatedMembers(
ProgramElementDoc[] members) {
return
toProgramElementDocArray(excludeDeprecatedMembersAsList(members));
}
/**
* Return array of class members whose documentation is to be generated.
* If the member is deprecated do not include such a member in the
* returned array.
*
* @param members Array of members to choose from.
* @return List List of eligible members for whom
* documentation is getting generated.
*/
public static List<ProgramElementDoc> excludeDeprecatedMembersAsList(
ProgramElementDoc[] members) {
List<ProgramElementDoc> list = new ArrayList<ProgramElementDoc>();
for (int i = 0; i < members.length; i++) {
if (members[i].tags("deprecated").length == 0) {
list.add(members[i]);
}
}
Collections.sort(list);
return list;
}
/**
* Return the list of ProgramElementDoc objects as Array.
*/
public static ProgramElementDoc[] toProgramElementDocArray(List<ProgramElementDoc> list) {
ProgramElementDoc[] pgmarr = new ProgramElementDoc[list.size()];
for (int i = 0; i < list.size(); i++) {
pgmarr[i] = list.get(i);
}
return pgmarr;
}
/**
* Return true if a non-public member found in the given array.
*
* @param members Array of members to look into.
* @return boolean True if non-public member found, false otherwise.
*/
public static boolean nonPublicMemberFound(ProgramElementDoc[] members) {
for (int i = 0; i < members.length; i++) {
if (!members[i].isPublic()) {
return true;
}
}
return false;
}
/**
* Search for the given method in the given class.
*
* @param cd Class to search into.
* @param method Method to be searched.
* @return MethodDoc Method found, null otherwise.
*/
public static MethodDoc findMethod(ClassDoc cd, MethodDoc method) {
MethodDoc[] methods = cd.methods();
for (int i = 0; i < methods.length; i++) {
if (executableMembersEqual(method, methods[i])) {
return methods[i];
}
}
return null;
}
/**
* @param member1 the first method to compare.
* @param member2 the second method to compare.
* @return true if member1 overrides/hides or is overriden/hidden by member2.
*/
public static boolean executableMembersEqual(ExecutableMemberDoc member1,
ExecutableMemberDoc member2) {
if (! (member1 instanceof MethodDoc && member2 instanceof MethodDoc))
return false;
MethodDoc method1 = (MethodDoc) member1;
MethodDoc method2 = (MethodDoc) member2;
if (method1.isStatic() && method2.isStatic()) {
Parameter[] targetParams = method1.parameters();
Parameter[] currentParams;
if (method1.name().equals(method2.name()) &&
(currentParams = method2.parameters()).length ==
targetParams.length) {
int j;
for (j = 0; j < targetParams.length; j++) {
if (! (targetParams[j].typeName().equals(
currentParams[j].typeName()) ||
currentParams[j].type() instanceof TypeVariable ||
targetParams[j].type() instanceof TypeVariable)) {
break;
}
}
if (j == targetParams.length) {
return true;
}
}
return false;
} else {
return method1.overrides(method2) ||
method2.overrides(method1) ||
member1 == member2;
}
}
/**
* According to
* <cite>The Java&trade; Language Specification</cite>,
* all the outer classes and static inner classes are core classes.
*/
public static boolean isCoreClass(ClassDoc cd) {
return cd.containingClass() == null || cd.isStatic();
}
public static boolean matches(ProgramElementDoc doc1,
ProgramElementDoc doc2) {
if (doc1 instanceof ExecutableMemberDoc &&
doc2 instanceof ExecutableMemberDoc) {
ExecutableMemberDoc ed1 = (ExecutableMemberDoc)doc1;
ExecutableMemberDoc ed2 = (ExecutableMemberDoc)doc2;
return executableMembersEqual(ed1, ed2);
} else {
return doc1.name().equals(doc2.name());
}
}
/**
* Copy the given directory contents from the source package directory
* to the generated documentation directory. For example for a package
* java.lang this method find out the source location of the package using
* {@link SourcePath} and if given directory is found in the source
* directory structure, copy the entire directory, to the generated
* documentation hierarchy.
*
* @param configuration The configuration of the current doclet.
* @param path The relative path to the directory to be copied.
* @param dir The original directory name to copy from.
* @param overwrite Overwrite files if true.
*/
public static void copyDocFiles(Configuration configuration, PackageDoc pd) {
copyDocFiles(configuration, DocPath.forPackage(pd).resolve(DocPaths.DOC_FILES));
}
public static void copyDocFiles(Configuration configuration, DocPath dir) {
try {
boolean first = true;
for (DocFile f : DocFile.list(configuration, StandardLocation.SOURCE_PATH, dir)) {
if (!f.isDirectory()) {
continue;
}
DocFile srcdir = f;
DocFile destdir = DocFile.createFileForOutput(configuration, dir);
if (srcdir.isSameFile(destdir)) {
continue;
}
for (DocFile srcfile: srcdir.list()) {
DocFile destfile = destdir.resolve(srcfile.getName());
if (srcfile.isFile()) {
if (destfile.exists() && !first) {
configuration.message.warning((SourcePosition) null,
"doclet.Copy_Overwrite_warning",
srcfile.getPath(), destdir.getPath());
} else {
configuration.message.notice(
"doclet.Copying_File_0_To_Dir_1",
srcfile.getPath(), destdir.getPath());
destfile.copyFile(srcfile);
}
} else if (srcfile.isDirectory()) {
if (configuration.copydocfilesubdirs
&& !configuration.shouldExcludeDocFileDir(srcfile.getName())) {
copyDocFiles(configuration, dir.resolve(srcfile.getName()));
}
}
}
first = false;
}
} catch (SecurityException exc) {
throw new DocletAbortException(exc);
} catch (IOException exc) {
throw new DocletAbortException(exc);
}
}
/**
* We want the list of types in alphabetical order. However, types are not
* comparable. We need a comparator for now.
*/
private static class TypeComparator implements Comparator<Type> {
public int compare(Type type1, Type type2) {
return type1.qualifiedTypeName().compareToIgnoreCase(
type2.qualifiedTypeName());
}
}
/**
* For the class return all implemented interfaces including the
* superinterfaces of the implementing interfaces, also iterate over for
* all the superclasses. For interface return all the extended interfaces
* as well as superinterfaces for those extended interfaces.
*
* @param type type whose implemented or
* super interfaces are sought.
* @param configuration the current configuration of the doclet.
* @param sort if true, return list of interfaces sorted alphabetically.
* @return List of all the required interfaces.
*/
public static List<Type> getAllInterfaces(Type type,
Configuration configuration, boolean sort) {
Map<ClassDoc,Type> results = sort ? new TreeMap<ClassDoc,Type>() : new LinkedHashMap<ClassDoc,Type>();
Type[] interfaceTypes = null;
Type superType = null;
if (type instanceof ParameterizedType) {
interfaceTypes = ((ParameterizedType) type).interfaceTypes();
superType = ((ParameterizedType) type).superclassType();
} else if (type instanceof ClassDoc) {
interfaceTypes = ((ClassDoc) type).interfaceTypes();
superType = ((ClassDoc) type).superclassType();
} else {
interfaceTypes = type.asClassDoc().interfaceTypes();
superType = type.asClassDoc().superclassType();
}
for (int i = 0; i < interfaceTypes.length; i++) {
Type interfaceType = interfaceTypes[i];
ClassDoc interfaceClassDoc = interfaceType.asClassDoc();
if (! (interfaceClassDoc.isPublic() ||
(configuration == null ||
isLinkable(interfaceClassDoc, configuration)))) {
continue;
}
results.put(interfaceClassDoc, interfaceType);
List<Type> superInterfaces = getAllInterfaces(interfaceType, configuration, sort);
for (Iterator<Type> iter = superInterfaces.iterator(); iter.hasNext(); ) {
Type t = iter.next();
results.put(t.asClassDoc(), t);
}
}
if (superType == null)
return new ArrayList<Type>(results.values());
//Try walking the tree.
addAllInterfaceTypes(results,
superType,
interfaceTypesOf(superType),
false, configuration);
List<Type> resultsList = new ArrayList<Type>(results.values());
if (sort) {
Collections.sort(resultsList, new TypeComparator());
}
return resultsList;
}
private static Type[] interfaceTypesOf(Type type) {
if (type instanceof AnnotatedType)
type = ((AnnotatedType)type).underlyingType();
return type instanceof ClassDoc ?
((ClassDoc)type).interfaceTypes() :
((ParameterizedType)type).interfaceTypes();
}
public static List<Type> getAllInterfaces(Type type, Configuration configuration) {
return getAllInterfaces(type, configuration, true);
}
private static void findAllInterfaceTypes(Map<ClassDoc,Type> results, ClassDoc c, boolean raw,
Configuration configuration) {
Type superType = c.superclassType();
if (superType == null)
return;
addAllInterfaceTypes(results, superType,
interfaceTypesOf(superType),
raw, configuration);
}
private static void findAllInterfaceTypes(Map<ClassDoc,Type> results, ParameterizedType p,
Configuration configuration) {
Type superType = p.superclassType();
if (superType == null)
return;
addAllInterfaceTypes(results, superType,
interfaceTypesOf(superType),
false, configuration);
}
private static void addAllInterfaceTypes(Map<ClassDoc,Type> results, Type type,
Type[] interfaceTypes, boolean raw,
Configuration configuration) {
for (int i = 0; i < interfaceTypes.length; i++) {
Type interfaceType = interfaceTypes[i];
ClassDoc interfaceClassDoc = interfaceType.asClassDoc();
if (! (interfaceClassDoc.isPublic() ||
(configuration != null &&
isLinkable(interfaceClassDoc, configuration)))) {
continue;
}
if (raw)
interfaceType = interfaceType.asClassDoc();
results.put(interfaceClassDoc, interfaceType);
List<Type> superInterfaces = getAllInterfaces(interfaceType, configuration);
for (Iterator<Type> iter = superInterfaces.iterator(); iter.hasNext(); ) {
Type superInterface = iter.next();
results.put(superInterface.asClassDoc(), superInterface);
}
}
if (type instanceof AnnotatedType)
type = ((AnnotatedType)type).underlyingType();
if (type instanceof ParameterizedType)
findAllInterfaceTypes(results, (ParameterizedType) type, configuration);
else if (((ClassDoc) type).typeParameters().length == 0)
findAllInterfaceTypes(results, (ClassDoc) type, raw, configuration);
else
findAllInterfaceTypes(results, (ClassDoc) type, true, configuration);
}
/**
* Enclose in quotes, used for paths and filenames that contains spaces
*/
public static String quote(String filepath) {
return ("\"" + filepath + "\"");
}
/**
* Given a package, return its name.
* @param packageDoc the package to check.
* @return the name of the given package.
*/
public static String getPackageName(PackageDoc packageDoc) {
return packageDoc == null || packageDoc.name().length() == 0 ?
DocletConstants.DEFAULT_PACKAGE_NAME : packageDoc.name();
}
/**
* Given a package, return its file name without the extension.
* @param packageDoc the package to check.
* @return the file name of the given package.
*/
public static String getPackageFileHeadName(PackageDoc packageDoc) {
return packageDoc == null || packageDoc.name().length() == 0 ?
DocletConstants.DEFAULT_PACKAGE_FILE_NAME : packageDoc.name();
}
/**
* Given a string, replace all occurrences of 'newStr' with 'oldStr'.
* @param originalStr the string to modify.
* @param oldStr the string to replace.
* @param newStr the string to insert in place of the old string.
*/
public static String replaceText(String originalStr, String oldStr,
String newStr) {
if (oldStr == null || newStr == null || oldStr.equals(newStr)) {
return originalStr;
}
return originalStr.replace(oldStr, newStr);
}
/**
* Given an annotation, return true if it should be documented and false
* otherwise.
*
* @param annotationDoc the annotation to check.
*
* @return true return true if it should be documented and false otherwise.
*/
public static boolean isDocumentedAnnotation(AnnotationTypeDoc annotationDoc) {
AnnotationDesc[] annotationDescList = annotationDoc.annotations();
for (int i = 0; i < annotationDescList.length; i++) {
if (annotationDescList[i].annotationType().qualifiedName().equals(
java.lang.annotation.Documented.class.getName())){
return true;
}
}
return false;
}
private static boolean isDeclarationTarget(AnnotationDesc targetAnno) {
// The error recovery steps here are analogous to TypeAnnotations
ElementValuePair[] elems = targetAnno.elementValues();
if (elems == null
|| elems.length != 1
|| !"value".equals(elems[0].element().name())
|| !(elems[0].value().value() instanceof AnnotationValue[]))
return true; // error recovery
AnnotationValue[] values = (AnnotationValue[])elems[0].value().value();
for (int i = 0; i < values.length; i++) {
Object value = values[i].value();
if (!(value instanceof FieldDoc))
return true; // error recovery
FieldDoc eValue = (FieldDoc)value;
if (Util.isJava5DeclarationElementType(eValue)) {
return true;
}
}
return false;
}
/**
* Returns true if the {@code annotationDoc} is to be treated
* as a declaration annotation, when targeting the
* {@code elemType} element type.
*
* @param annotationDoc the annotationDoc to check
* @param elemType the targeted elemType
* @return true if annotationDoc is a declaration annotation
*/
public static boolean isDeclarationAnnotation(AnnotationTypeDoc annotationDoc,
boolean isJava5DeclarationLocation) {
if (!isJava5DeclarationLocation)
return false;
AnnotationDesc[] annotationDescList = annotationDoc.annotations();
// Annotations with no target are treated as declaration as well
if (annotationDescList.length==0)
return true;
for (int i = 0; i < annotationDescList.length; i++) {
if (annotationDescList[i].annotationType().qualifiedName().equals(
java.lang.annotation.Target.class.getName())) {
if (isDeclarationTarget(annotationDescList[i]))
return true;
}
}
return false;
}
/**
* Return true if this class is linkable and false if we can't link to the
* desired class.
* <br>
* <b>NOTE:</b> You can only link to external classes if they are public or
* protected.
*
* @param classDoc the class to check.
* @param configuration the current configuration of the doclet.
*
* @return true if this class is linkable and false if we can't link to the
* desired class.
*/
public static boolean isLinkable(ClassDoc classDoc,
Configuration configuration) {
return
((classDoc.isIncluded() && configuration.isGeneratedDoc(classDoc))) ||
(configuration.extern.isExternal(classDoc) &&
(classDoc.isPublic() || classDoc.isProtected()));
}
/**
* Given a class, return the closest visible super class.
*
* @param classDoc the class we are searching the parent for.
* @param configuration the current configuration of the doclet.
* @return the closest visible super class. Return null if it cannot
* be found (i.e. classDoc is java.lang.Object).
*/
public static Type getFirstVisibleSuperClass(ClassDoc classDoc,
Configuration configuration) {
if (classDoc == null) {
return null;
}
Type sup = classDoc.superclassType();
ClassDoc supClassDoc = classDoc.superclass();
while (sup != null &&
(! (supClassDoc.isPublic() ||
isLinkable(supClassDoc, configuration))) ) {
if (supClassDoc.superclass().qualifiedName().equals(supClassDoc.qualifiedName()))
break;
sup = supClassDoc.superclassType();
supClassDoc = supClassDoc.superclass();
}
if (classDoc.equals(supClassDoc)) {
return null;
}
return sup;
}
/**
* Given a class, return the closest visible super class.
*
* @param classDoc the class we are searching the parent for.
* @param configuration the current configuration of the doclet.
* @return the closest visible super class. Return null if it cannot
* be found (i.e. classDoc is java.lang.Object).
*/
public static ClassDoc getFirstVisibleSuperClassCD(ClassDoc classDoc,
Configuration configuration) {
if (classDoc == null) {
return null;
}
ClassDoc supClassDoc = classDoc.superclass();
while (supClassDoc != null &&
(! (supClassDoc.isPublic() ||
isLinkable(supClassDoc, configuration))) ) {
supClassDoc = supClassDoc.superclass();
}
if (classDoc.equals(supClassDoc)) {
return null;
}
return supClassDoc;
}
/**
* Given a ClassDoc, return the name of its type (Class, Interface, etc.).
*
* @param cd the ClassDoc to check.
* @param lowerCaseOnly true if you want the name returned in lower case.
* If false, the first letter of the name is capitalized.
* @return
*/
public static String getTypeName(Configuration config,
ClassDoc cd, boolean lowerCaseOnly) {
String typeName = "";
if (cd.isOrdinaryClass()) {
typeName = "doclet.Class";
} else if (cd.isInterface()) {
typeName = "doclet.Interface";
} else if (cd.isException()) {
typeName = "doclet.Exception";
} else if (cd.isError()) {
typeName = "doclet.Error";
} else if (cd.isAnnotationType()) {
typeName = "doclet.AnnotationType";
} else if (cd.isEnum()) {
typeName = "doclet.Enum";
}
return config.getText(
lowerCaseOnly ? StringUtils.toLowerCase(typeName) : typeName);
}
/**
* Replace all tabs in a string with the appropriate number of spaces.
* The string may be a multi-line string.
* @param configuration the doclet configuration defining the setting for the
* tab length.
* @param text the text for which the tabs should be expanded
* @return the text with all tabs expanded
*/
public static String replaceTabs(Configuration configuration, String text) {
if (text.indexOf("\t") == -1)
return text;
final int tabLength = configuration.sourcetab;
final String whitespace = configuration.tabSpaces;
final int textLength = text.length();
StringBuilder result = new StringBuilder(textLength);
int pos = 0;
int lineLength = 0;
for (int i = 0; i < textLength; i++) {
char ch = text.charAt(i);
switch (ch) {
case '\n': case '\r':
lineLength = 0;
break;
case '\t':
result.append(text, pos, i);
int spaceCount = tabLength - lineLength % tabLength;
result.append(whitespace, 0, spaceCount);
lineLength += spaceCount;
pos = i + 1;
break;
default:
lineLength++;
}
}
result.append(text, pos, textLength);
return result.toString();
}
public static String normalizeNewlines(String text) {
StringBuilder sb = new StringBuilder();
final int textLength = text.length();
final String NL = DocletConstants.NL;
int pos = 0;
for (int i = 0; i < textLength; i++) {
char ch = text.charAt(i);
switch (ch) {
case '\n':
sb.append(text, pos, i);
sb.append(NL);
pos = i + 1;
break;
case '\r':
sb.append(text, pos, i);
sb.append(NL);
if (i + 1 < textLength && text.charAt(i + 1) == '\n')
i++;
pos = i + 1;
break;
}
}
sb.append(text, pos, textLength);
return sb.toString();
}
/**
* The documentation for values() and valueOf() in Enums are set by the
* doclet.
*/
public static void setEnumDocumentation(Configuration configuration,
ClassDoc classDoc) {
MethodDoc[] methods = classDoc.methods();
for (int j = 0; j < methods.length; j++) {
MethodDoc currentMethod = methods[j];
if (currentMethod.name().equals("values") &&
currentMethod.parameters().length == 0) {
StringBuilder sb = new StringBuilder();
sb.append(configuration.getText("doclet.enum_values_doc.main", classDoc.name()));
sb.append("\n@return ");
sb.append(configuration.getText("doclet.enum_values_doc.return"));
currentMethod.setRawCommentText(sb.toString());
} else if (currentMethod.name().equals("valueOf") &&
currentMethod.parameters().length == 1) {
Type paramType = currentMethod.parameters()[0].type();
if (paramType != null &&
paramType.qualifiedTypeName().equals(String.class.getName())) {
StringBuilder sb = new StringBuilder();
sb.append(configuration.getText("doclet.enum_valueof_doc.main", classDoc.name()));
sb.append("\n@param name ");
sb.append(configuration.getText("doclet.enum_valueof_doc.param_name"));
sb.append("\n@return ");
sb.append(configuration.getText("doclet.enum_valueof_doc.return"));
sb.append("\n@throws IllegalArgumentException ");
sb.append(configuration.getText("doclet.enum_valueof_doc.throws_ila"));
sb.append("\n@throws NullPointerException ");
sb.append(configuration.getText("doclet.enum_valueof_doc.throws_npe"));
currentMethod.setRawCommentText(sb.toString());
}
}
}
}
/**
* Return true if the given Doc is deprecated.
*
* @param doc the Doc to check.
* @return true if the given Doc is deprecated.
*/
public static boolean isDeprecated(Doc doc) {
if (doc.tags("deprecated").length > 0) {
return true;
}
AnnotationDesc[] annotationDescList;
if (doc instanceof PackageDoc)
annotationDescList = ((PackageDoc)doc).annotations();
else
annotationDescList = ((ProgramElementDoc)doc).annotations();
for (int i = 0; i < annotationDescList.length; i++) {
if (annotationDescList[i].annotationType().qualifiedName().equals(
java.lang.Deprecated.class.getName())){
return true;
}
}
return false;
}
/**
* A convenience method to get property name from the name of the
* getter or setter method.
* @param name name of the getter or setter method.
* @return the name of the property of the given setter of getter.
*/
public static String propertyNameFromMethodName(Configuration configuration, String name) {
String propertyName = null;
if (name.startsWith("get") || name.startsWith("set")) {
propertyName = name.substring(3);
} else if (name.startsWith("is")) {
propertyName = name.substring(2);
}
if ((propertyName == null) || propertyName.isEmpty()){
return "";
}
return propertyName.substring(0, 1).toLowerCase(configuration.getLocale())
+ propertyName.substring(1);
}
/**
* In case of JavaFX mode on, filters out classes that are private,
* package private or having the @treatAsPrivate annotation. Those are not
* documented in JavaFX mode.
*
* @param classes array of classes to be filtered.
* @param javafx set to true if in JavaFX mode.
* @return list of filtered classes.
*/
public static ClassDoc[] filterOutPrivateClasses(final ClassDoc[] classes,
boolean javafx) {
if (!javafx) {
return classes;
}
final List<ClassDoc> filteredOutClasses =
new ArrayList<ClassDoc>(classes.length);
for (ClassDoc classDoc : classes) {
if (classDoc.isPrivate() || classDoc.isPackagePrivate()) {
continue;
}
Tag[] aspTags = classDoc.tags("treatAsPrivate");
if (aspTags != null && aspTags.length > 0) {
continue;
}
filteredOutClasses.add(classDoc);
}
return filteredOutClasses.toArray(new ClassDoc[0]);
}
/**
* Test whether the given FieldDoc is one of the declaration annotation ElementTypes
* defined in Java 5.
* Instead of testing for one of the new enum constants added in Java 8, test for
* the old constants. This prevents bootstrapping problems.
*
* @param elt The FieldDoc to test
* @return true, iff the given ElementType is one of the constants defined in Java 5
* @since 1.8
*/
public static boolean isJava5DeclarationElementType(FieldDoc elt) {
return elt.name().contentEquals(ElementType.ANNOTATION_TYPE.name()) ||
elt.name().contentEquals(ElementType.CONSTRUCTOR.name()) ||
elt.name().contentEquals(ElementType.FIELD.name()) ||
elt.name().contentEquals(ElementType.LOCAL_VARIABLE.name()) ||
elt.name().contentEquals(ElementType.METHOD.name()) ||
elt.name().contentEquals(ElementType.PACKAGE.name()) ||
elt.name().contentEquals(ElementType.PARAMETER.name()) ||
elt.name().contentEquals(ElementType.TYPE.name());
}
}

780
jdkSrc/jdk8/com/sun/tools/doclets/internal/toolkit/util/VisibleMemberMap.java Normal file
View File

@@ -0,0 +1,780 @@
/*
* Copyright (c) 1999, 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 com.sun.tools.doclets.internal.toolkit.util;
import java.util.*;
import java.util.regex.Pattern;
import com.sun.javadoc.*;
import com.sun.tools.doclets.internal.toolkit.*;
/**
* A data structure that encapsulates the visible members of a particular
* type for a given class tree. To use this data structor, you must specify
* the type of member you are interested in (nested class, field, constructor
* or method) and the leaf of the class tree. The data structure will map
* all visible members in the leaf and classes above the leaf in the tree.
*
* <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 Atul M Dambalkar
* @author Jamie Ho (rewrite)
*/
public class VisibleMemberMap {
private boolean noVisibleMembers = true;
public static final int INNERCLASSES = 0;
public static final int ENUM_CONSTANTS = 1;
public static final int FIELDS = 2;
public static final int CONSTRUCTORS = 3;
public static final int METHODS = 4;
public static final int ANNOTATION_TYPE_FIELDS = 5;
public static final int ANNOTATION_TYPE_MEMBER_OPTIONAL = 6;
public static final int ANNOTATION_TYPE_MEMBER_REQUIRED = 7;
public static final int PROPERTIES = 8;
/**
* The total number of member types is {@value}.
*/
public static final int NUM_MEMBER_TYPES = 9;
public static final String STARTLEVEL = "start";
/**
* List of ClassDoc objects for which ClassMembers objects are built.
*/
private final List<ClassDoc> visibleClasses = new ArrayList<ClassDoc>();
/**
* Map for each member name on to a map which contains members with same
* name-signature. The mapped map will contain mapping for each MemberDoc
* onto it's respecive level string.
*/
private final Map<Object,Map<ProgramElementDoc,String>> memberNameMap = new HashMap<Object,Map<ProgramElementDoc,String>>();
/**
* Map of class and it's ClassMembers object.
*/
private final Map<ClassDoc,ClassMembers> classMap = new HashMap<ClassDoc,ClassMembers>();
/**
* Type whose visible members are requested. This is the leaf of
* the class tree being mapped.
*/
private final ClassDoc classdoc;
/**
* Member kind: InnerClasses/Fields/Methods?
*/
private final int kind;
/**
* The configuration this VisibleMemberMap was created with.
*/
private final Configuration configuration;
private static final Map<ClassDoc, ProgramElementDoc[]> propertiesCache =
new HashMap<ClassDoc, ProgramElementDoc[]>();
private static final Map<ProgramElementDoc, ProgramElementDoc> classPropertiesMap =
new HashMap<ProgramElementDoc, ProgramElementDoc>();
private static final Map<ProgramElementDoc, GetterSetter> getterSetterMap =
new HashMap<ProgramElementDoc, GetterSetter>();
/**
* Construct a VisibleMemberMap of the given type for the given
* class.
*
* @param classdoc the class whose members are being mapped.
* @param kind the kind of member that is being mapped.
* @param configuration the configuration to use to construct this
* VisibleMemberMap. If the field configuration.nodeprecated is true the
* deprecated members are excluded from the map. If the field
* configuration.javafx is true the JavaFX features are used.
*/
public VisibleMemberMap(ClassDoc classdoc,
int kind,
Configuration configuration) {
this.classdoc = classdoc;
this.kind = kind;
this.configuration = configuration;
new ClassMembers(classdoc, STARTLEVEL).build();
}
/**
* Return the list of visible classes in this map.
*
* @return the list of visible classes in this map.
*/
public List<ClassDoc> getVisibleClassesList() {
sort(visibleClasses);
return visibleClasses;
}
/**
* Returns the property field documentation belonging to the given member.
* @param ped the member for which the property documentation is needed.
* @return the property field documentation, null if there is none.
*/
public ProgramElementDoc getPropertyMemberDoc(ProgramElementDoc ped) {
return classPropertiesMap.get(ped);
}
/**
* Returns the getter documentation belonging to the given property method.
* @param propertyMethod the method for which the getter is needed.
* @return the getter documentation, null if there is none.
*/
public ProgramElementDoc getGetterForProperty(ProgramElementDoc propertyMethod) {
return getterSetterMap.get(propertyMethod).getGetter();
}
/**
* Returns the setter documentation belonging to the given property method.
* @param propertyMethod the method for which the setter is needed.
* @return the setter documentation, null if there is none.
*/
public ProgramElementDoc getSetterForProperty(ProgramElementDoc propertyMethod) {
return getterSetterMap.get(propertyMethod).getSetter();
}
/**
* Return the package private members inherited by the class. Only return
* if parent is package private and not documented.
*
* @param configuration the current configuration of the doclet.
* @return the package private members inherited by the class.
*/
private List<ProgramElementDoc> getInheritedPackagePrivateMethods(Configuration configuration) {
List<ProgramElementDoc> results = new ArrayList<ProgramElementDoc>();
for (Iterator<ClassDoc> iter = visibleClasses.iterator(); iter.hasNext(); ) {
ClassDoc currentClass = iter.next();
if (currentClass != classdoc &&
currentClass.isPackagePrivate() &&
!Util.isLinkable(currentClass, configuration)) {
// Document these members in the child class because
// the parent is inaccessible.
results.addAll(getMembersFor(currentClass));
}
}
return results;
}
/**
* Return the visible members of the class being mapped. Also append at the
* end of the list members that are inherited by inaccessible parents. We
* document these members in the child because the parent is not documented.
*
* @param configuration the current configuration of the doclet.
*/
public List<ProgramElementDoc> getLeafClassMembers(Configuration configuration) {
List<ProgramElementDoc> result = getMembersFor(classdoc);
result.addAll(getInheritedPackagePrivateMethods(configuration));
return result;
}
/**
* Retrn the list of members for the given class.
*
* @param cd the class to retrieve the list of visible members for.
*
* @return the list of members for the given class.
*/
public List<ProgramElementDoc> getMembersFor(ClassDoc cd) {
ClassMembers clmembers = classMap.get(cd);
if (clmembers == null) {
return new ArrayList<ProgramElementDoc>();
}
return clmembers.getMembers();
}
/**
* Sort the given mixed list of classes and interfaces to a list of
* classes followed by interfaces traversed. Don't sort alphabetically.
*/
private void sort(List<ClassDoc> list) {
List<ClassDoc> classes = new ArrayList<ClassDoc>();
List<ClassDoc> interfaces = new ArrayList<ClassDoc>();
for (int i = 0; i < list.size(); i++) {
ClassDoc cd = list.get(i);
if (cd.isClass()) {
classes.add(cd);
} else {
interfaces.add(cd);
}
}
list.clear();
list.addAll(classes);
list.addAll(interfaces);
}
private void fillMemberLevelMap(List<ProgramElementDoc> list, String level) {
for (int i = 0; i < list.size(); i++) {
Object key = getMemberKey(list.get(i));
Map<ProgramElementDoc,String> memberLevelMap = memberNameMap.get(key);
if (memberLevelMap == null) {
memberLevelMap = new HashMap<ProgramElementDoc,String>();
memberNameMap.put(key, memberLevelMap);
}
memberLevelMap.put(list.get(i), level);
}
}
private void purgeMemberLevelMap(List<ProgramElementDoc> list, String level) {
for (int i = 0; i < list.size(); i++) {
Object key = getMemberKey(list.get(i));
Map<ProgramElementDoc, String> memberLevelMap = memberNameMap.get(key);
if (memberLevelMap != null && level.equals(memberLevelMap.get(list.get(i))))
memberLevelMap.remove(list.get(i));
}
}
/**
* Represents a class member. We should be able to just use a
* ProgramElementDoc instead of this class, but that doesn't take
* type variables in consideration when comparing.
*/
private class ClassMember {
private Set<ProgramElementDoc> members;
public ClassMember(ProgramElementDoc programElementDoc) {
members = new HashSet<ProgramElementDoc>();
members.add(programElementDoc);
}
public void addMember(ProgramElementDoc programElementDoc) {
members.add(programElementDoc);
}
public boolean isEqual(MethodDoc member) {
for (Iterator<ProgramElementDoc> iter = members.iterator(); iter.hasNext(); ) {
MethodDoc member2 = (MethodDoc) iter.next();
if (Util.executableMembersEqual(member, member2)) {
members.add(member);
return true;
}
}
return false;
}
}
/**
* A data structure that represents the class members for
* a visible class.
*/
private class ClassMembers {
/**
* The mapping class, whose inherited members are put in the
* {@link #members} list.
*/
private ClassDoc mappingClass;
/**
* List of inherited members from the mapping class.
*/
private List<ProgramElementDoc> members = new ArrayList<ProgramElementDoc>();
/**
* Level/Depth of inheritance.
*/
private String level;
/**
* Return list of inherited members from mapping class.
*
* @return List Inherited members.
*/
public List<ProgramElementDoc> getMembers() {
return members;
}
private ClassMembers(ClassDoc mappingClass, String level) {
this.mappingClass = mappingClass;
this.level = level;
if (classMap.containsKey(mappingClass) &&
level.startsWith(classMap.get(mappingClass).level)) {
//Remove lower level class so that it can be replaced with
//same class found at higher level.
purgeMemberLevelMap(getClassMembers(mappingClass, false),
classMap.get(mappingClass).level);
classMap.remove(mappingClass);
visibleClasses.remove(mappingClass);
}
if (!classMap.containsKey(mappingClass)) {
classMap.put(mappingClass, this);
visibleClasses.add(mappingClass);
}
}
private void build() {
if (kind == CONSTRUCTORS) {
addMembers(mappingClass);
} else {
mapClass();
}
}
private void mapClass() {
addMembers(mappingClass);
ClassDoc[] interfaces = mappingClass.interfaces();
for (int i = 0; i < interfaces.length; i++) {
String locallevel = level + 1;
ClassMembers cm = new ClassMembers(interfaces[i], locallevel);
cm.mapClass();
}
if (mappingClass.isClass()) {
ClassDoc superclass = mappingClass.superclass();
if (!(superclass == null || mappingClass.equals(superclass))) {
ClassMembers cm = new ClassMembers(superclass,
level + "c");
cm.mapClass();
}
}
}
/**
* Get all the valid members from the mapping class. Get the list of
* members for the class to be included into(ctii), also get the level
* string for ctii. If mapping class member is not already in the
* inherited member list and if it is visible in the ctii and not
* overridden, put such a member in the inherited member list.
* Adjust member-level-map, class-map.
*/
private void addMembers(ClassDoc fromClass) {
List<ProgramElementDoc> cdmembers = getClassMembers(fromClass, true);
List<ProgramElementDoc> incllist = new ArrayList<ProgramElementDoc>();
for (int i = 0; i < cdmembers.size(); i++) {
ProgramElementDoc pgmelem = cdmembers.get(i);
if (!found(members, pgmelem) &&
memberIsVisible(pgmelem) &&
!isOverridden(pgmelem, level) &&
!isTreatedAsPrivate(pgmelem)) {
incllist.add(pgmelem);
}
}
if (incllist.size() > 0) {
noVisibleMembers = false;
}
members.addAll(incllist);
fillMemberLevelMap(getClassMembers(fromClass, false), level);
}
private boolean isTreatedAsPrivate(ProgramElementDoc pgmelem) {
if (!configuration.javafx) {
return false;
}
Tag[] aspTags = pgmelem.tags("@treatAsPrivate");
boolean result = (aspTags != null) && (aspTags.length > 0);
return result;
}
/**
* Is given doc item visible in given classdoc in terms fo inheritance?
* The given doc item is visible in the given classdoc if it is public
* or protected and if it is package-private if it's containing class
* is in the same package as the given classdoc.
*/
private boolean memberIsVisible(ProgramElementDoc pgmdoc) {
if (pgmdoc.containingClass().equals(classdoc)) {
//Member is in class that we are finding visible members for.
//Of course it is visible.
return true;
} else if (pgmdoc.isPrivate()) {
//Member is in super class or implemented interface.
//Private, so not inherited.
return false;
} else if (pgmdoc.isPackagePrivate()) {
//Member is package private. Only return true if its class is in
//same package.
return pgmdoc.containingClass().containingPackage().equals(
classdoc.containingPackage());
} else {
//Public members are always inherited.
return true;
}
}
/**
* Return all available class members.
*/
private List<ProgramElementDoc> getClassMembers(ClassDoc cd, boolean filter) {
if (cd.isEnum() && kind == CONSTRUCTORS) {
//If any of these rules are hit, return empty array because
//we don't document these members ever.
return Arrays.asList(new ProgramElementDoc[] {});
}
ProgramElementDoc[] members = null;
switch (kind) {
case ANNOTATION_TYPE_FIELDS:
members = cd.fields(filter);
break;
case ANNOTATION_TYPE_MEMBER_OPTIONAL:
members = cd.isAnnotationType() ?
filter((AnnotationTypeDoc) cd, false) :
new AnnotationTypeElementDoc[] {};
break;
case ANNOTATION_TYPE_MEMBER_REQUIRED:
members = cd.isAnnotationType() ?
filter((AnnotationTypeDoc) cd, true) :
new AnnotationTypeElementDoc[] {};
break;
case INNERCLASSES:
members = cd.innerClasses(filter);
break;
case ENUM_CONSTANTS:
members = cd.enumConstants();
break;
case FIELDS:
members = cd.fields(filter);
break;
case CONSTRUCTORS:
members = cd.constructors();
break;
case METHODS:
members = cd.methods(filter);
checkOnPropertiesTags((MethodDoc[])members);
break;
case PROPERTIES:
members = properties(cd, filter);
break;
default:
members = new ProgramElementDoc[0];
}
// Deprected members should be excluded or not?
if (configuration.nodeprecated) {
return Util.excludeDeprecatedMembersAsList(members);
}
return Arrays.asList(members);
}
/**
* Filter the annotation type members and return either the required
* members or the optional members, depending on the value of the
* required parameter.
*
* @param doc The annotation type to process.
* @param required
* @return the annotation type members and return either the required
* members or the optional members, depending on the value of the
* required parameter.
*/
private AnnotationTypeElementDoc[] filter(AnnotationTypeDoc doc,
boolean required) {
AnnotationTypeElementDoc[] members = doc.elements();
List<AnnotationTypeElementDoc> targetMembers = new ArrayList<AnnotationTypeElementDoc>();
for (int i = 0; i < members.length; i++) {
if ((required && members[i].defaultValue() == null) ||
((!required) && members[i].defaultValue() != null)){
targetMembers.add(members[i]);
}
}
return targetMembers.toArray(new AnnotationTypeElementDoc[]{});
}
private boolean found(List<ProgramElementDoc> list, ProgramElementDoc elem) {
for (int i = 0; i < list.size(); i++) {
ProgramElementDoc pgmelem = list.get(i);
if (Util.matches(pgmelem, elem)) {
return true;
}
}
return false;
}
/**
* Is member overridden? The member is overridden if it is found in the
* same level hierarchy e.g. member at level "11" overrides member at
* level "111".
*/
private boolean isOverridden(ProgramElementDoc pgmdoc, String level) {
Map<?,String> memberLevelMap = (Map<?,String>) memberNameMap.get(getMemberKey(pgmdoc));
if (memberLevelMap == null)
return false;
String mappedlevel = null;
Iterator<String> iterator = memberLevelMap.values().iterator();
while (iterator.hasNext()) {
mappedlevel = iterator.next();
if (mappedlevel.equals(STARTLEVEL) ||
(level.startsWith(mappedlevel) &&
!level.equals(mappedlevel))) {
return true;
}
}
return false;
}
private ProgramElementDoc[] properties(final ClassDoc cd, final boolean filter) {
final MethodDoc[] allMethods = cd.methods(filter);
final FieldDoc[] allFields = cd.fields(false);
if (propertiesCache.containsKey(cd)) {
return propertiesCache.get(cd);
}
final List<MethodDoc> result = new ArrayList<MethodDoc>();
for (final MethodDoc propertyMethod : allMethods) {
if (!isPropertyMethod(propertyMethod)) {
continue;
}
final MethodDoc getter = getterForField(allMethods, propertyMethod);
final MethodDoc setter = setterForField(allMethods, propertyMethod);
final FieldDoc field = fieldForProperty(allFields, propertyMethod);
addToPropertiesMap(setter, getter, propertyMethod, field);
getterSetterMap.put(propertyMethod, new GetterSetter(getter, setter));
result.add(propertyMethod);
}
final ProgramElementDoc[] resultAray =
result.toArray(new ProgramElementDoc[result.size()]);
propertiesCache.put(cd, resultAray);
return resultAray;
}
private void addToPropertiesMap(MethodDoc setter,
MethodDoc getter,
MethodDoc propertyMethod,
FieldDoc field) {
if ((field == null)
|| (field.getRawCommentText() == null)
|| field.getRawCommentText().length() == 0) {
addToPropertiesMap(setter, propertyMethod);
addToPropertiesMap(getter, propertyMethod);
addToPropertiesMap(propertyMethod, propertyMethod);
} else {
addToPropertiesMap(getter, field);
addToPropertiesMap(setter, field);
addToPropertiesMap(propertyMethod, field);
}
}
private void addToPropertiesMap(ProgramElementDoc propertyMethod,
ProgramElementDoc commentSource) {
if (null == propertyMethod || null == commentSource) {
return;
}
final String methodRawCommentText = propertyMethod.getRawCommentText();
/* The second condition is required for the property buckets. In
* this case the comment is at the property method (not at the field)
* and it needs to be listed in the map.
*/
if ((null == methodRawCommentText || 0 == methodRawCommentText.length())
|| propertyMethod.equals(commentSource)) {
classPropertiesMap.put(propertyMethod, commentSource);
}
}
private MethodDoc getterForField(MethodDoc[] methods,
MethodDoc propertyMethod) {
final String propertyMethodName = propertyMethod.name();
final String fieldName =
propertyMethodName.substring(0,
propertyMethodName.lastIndexOf("Property"));
final String fieldNameUppercased =
"" + Character.toUpperCase(fieldName.charAt(0))
+ fieldName.substring(1);
final String getterNamePattern;
final String fieldTypeName = propertyMethod.returnType().toString();
if ("boolean".equals(fieldTypeName)
|| fieldTypeName.endsWith("BooleanProperty")) {
getterNamePattern = "(is|get)" + fieldNameUppercased;
} else {
getterNamePattern = "get" + fieldNameUppercased;
}
for (MethodDoc methodDoc : methods) {
if (Pattern.matches(getterNamePattern, methodDoc.name())) {
if (0 == methodDoc.parameters().length
&& (methodDoc.isPublic() || methodDoc.isProtected())) {
return methodDoc;
}
}
}
return null;
}
private MethodDoc setterForField(MethodDoc[] methods,
MethodDoc propertyMethod) {
final String propertyMethodName = propertyMethod.name();
final String fieldName =
propertyMethodName.substring(0,
propertyMethodName.lastIndexOf("Property"));
final String fieldNameUppercased =
"" + Character.toUpperCase(fieldName.charAt(0))
+ fieldName.substring(1);
final String setter = "set" + fieldNameUppercased;
for (MethodDoc methodDoc : methods) {
if (setter.equals(methodDoc.name())) {
if (1 == methodDoc.parameters().length
&& "void".equals(methodDoc.returnType().simpleTypeName())
&& (methodDoc.isPublic() || methodDoc.isProtected())) {
return methodDoc;
}
}
}
return null;
}
private FieldDoc fieldForProperty(FieldDoc[] fields, MethodDoc property) {
for (FieldDoc field : fields) {
final String fieldName = field.name();
final String propertyName = fieldName + "Property";
if (propertyName.equals(property.name())) {
return field;
}
}
return null;
}
// properties aren't named setA* or getA*
private final Pattern pattern = Pattern.compile("[sg]et\\p{Upper}.*");
private boolean isPropertyMethod(MethodDoc method) {
if (!configuration.javafx) {
return false;
}
if (!method.name().endsWith("Property")) {
return false;
}
if (! memberIsVisible(method)) {
return false;
}
if (pattern.matcher(method.name()).matches()) {
return false;
}
if (method.typeParameters().length > 0) {
return false;
}
return 0 == method.parameters().length
&& !"void".equals(method.returnType().simpleTypeName());
}
private void checkOnPropertiesTags(MethodDoc[] members) {
for (MethodDoc methodDoc: members) {
if (methodDoc.isIncluded()) {
for (Tag tag: methodDoc.tags()) {
String tagName = tag.name();
if (tagName.equals("@propertySetter")
|| tagName.equals("@propertyGetter")
|| tagName.equals("@propertyDescription")) {
if (!isPropertyGetterOrSetter(members, methodDoc)) {
configuration.message.warning(tag.position(),
"doclet.javafx_tag_misuse");
}
break;
}
}
}
}
}
private boolean isPropertyGetterOrSetter(MethodDoc[] members,
MethodDoc methodDoc) {
boolean found = false;
String propertyName = Util.propertyNameFromMethodName(configuration, methodDoc.name());
if (!propertyName.isEmpty()) {
String propertyMethodName = propertyName + "Property";
for (MethodDoc member: members) {
if (member.name().equals(propertyMethodName)) {
found = true;
break;
}
}
}
return found;
}
}
private class GetterSetter {
private final ProgramElementDoc getter;
private final ProgramElementDoc setter;
public GetterSetter(ProgramElementDoc getter, ProgramElementDoc setter) {
this.getter = getter;
this.setter = setter;
}
public ProgramElementDoc getGetter() {
return getter;
}
public ProgramElementDoc getSetter() {
return setter;
}
}
/**
* Return true if this map has no visible members.
*
* @return true if this map has no visible members.
*/
public boolean noVisibleMembers() {
return noVisibleMembers;
}
private ClassMember getClassMember(MethodDoc member) {
for (Iterator<?> iter = memberNameMap.keySet().iterator(); iter.hasNext();) {
Object key = iter.next();
if (key instanceof String) {
continue;
} else if (((ClassMember) key).isEqual(member)) {
return (ClassMember) key;
}
}
return new ClassMember(member);
}
/**
* Return the key to the member map for the given member.
*/
private Object getMemberKey(ProgramElementDoc doc) {
if (doc.isConstructor()) {
return doc.name() + ((ExecutableMemberDoc)doc).signature();
} else if (doc.isMethod()) {
return getClassMember((MethodDoc) doc);
} else if (doc.isField() || doc.isEnumConstant() || doc.isAnnotationTypeElement()) {
return doc.name();
} else { // it's a class or interface
String classOrIntName = doc.name();
//Strip off the containing class name because we only want the member name.
classOrIntName = classOrIntName.indexOf('.') != 0 ? classOrIntName.substring(classOrIntName.lastIndexOf('.'), classOrIntName.length()) : classOrIntName;
return "clint" + classOrIntName;
}
}
}

Some files were not shown because too many files have changed in this diff Show More