1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/Util.java Wed Apr 27 01:34:52 2016 +0800
1.3 @@ -0,0 +1,792 @@
1.4 +/*
1.5 + * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package com.sun.tools.doclets.internal.toolkit.util;
1.30 +
1.31 +import java.io.*;
1.32 +import java.lang.annotation.ElementType;
1.33 +import java.util.*;
1.34 +import javax.tools.StandardLocation;
1.35 +
1.36 +import com.sun.javadoc.*;
1.37 +import com.sun.javadoc.AnnotationDesc.ElementValuePair;
1.38 +import com.sun.tools.doclets.internal.toolkit.*;
1.39 +import com.sun.tools.javac.util.StringUtils;
1.40 +
1.41 +/**
1.42 + * Utilities Class for Doclets.
1.43 + *
1.44 + * <p><b>This is NOT part of any supported API.
1.45 + * If you write code that depends on this, you do so at your own risk.
1.46 + * This code and its internal interfaces are subject to change or
1.47 + * deletion without notice.</b>
1.48 + *
1.49 + * @author Atul M Dambalkar
1.50 + * @author Jamie Ho
1.51 + */
1.52 +public class Util {
1.53 +
1.54 + /**
1.55 + * Return array of class members whose documentation is to be generated.
1.56 + * If the member is deprecated do not include such a member in the
1.57 + * returned array.
1.58 + *
1.59 + * @param members Array of members to choose from.
1.60 + * @return ProgramElementDoc[] Array of eligible members for whom
1.61 + * documentation is getting generated.
1.62 + */
1.63 + public static ProgramElementDoc[] excludeDeprecatedMembers(
1.64 + ProgramElementDoc[] members) {
1.65 + return
1.66 + toProgramElementDocArray(excludeDeprecatedMembersAsList(members));
1.67 + }
1.68 +
1.69 + /**
1.70 + * Return array of class members whose documentation is to be generated.
1.71 + * If the member is deprecated do not include such a member in the
1.72 + * returned array.
1.73 + *
1.74 + * @param members Array of members to choose from.
1.75 + * @return List List of eligible members for whom
1.76 + * documentation is getting generated.
1.77 + */
1.78 + public static List<ProgramElementDoc> excludeDeprecatedMembersAsList(
1.79 + ProgramElementDoc[] members) {
1.80 + List<ProgramElementDoc> list = new ArrayList<ProgramElementDoc>();
1.81 + for (int i = 0; i < members.length; i++) {
1.82 + if (members[i].tags("deprecated").length == 0) {
1.83 + list.add(members[i]);
1.84 + }
1.85 + }
1.86 + Collections.sort(list);
1.87 + return list;
1.88 + }
1.89 +
1.90 + /**
1.91 + * Return the list of ProgramElementDoc objects as Array.
1.92 + */
1.93 + public static ProgramElementDoc[] toProgramElementDocArray(List<ProgramElementDoc> list) {
1.94 + ProgramElementDoc[] pgmarr = new ProgramElementDoc[list.size()];
1.95 + for (int i = 0; i < list.size(); i++) {
1.96 + pgmarr[i] = list.get(i);
1.97 + }
1.98 + return pgmarr;
1.99 + }
1.100 +
1.101 + /**
1.102 + * Return true if a non-public member found in the given array.
1.103 + *
1.104 + * @param members Array of members to look into.
1.105 + * @return boolean True if non-public member found, false otherwise.
1.106 + */
1.107 + public static boolean nonPublicMemberFound(ProgramElementDoc[] members) {
1.108 + for (int i = 0; i < members.length; i++) {
1.109 + if (!members[i].isPublic()) {
1.110 + return true;
1.111 + }
1.112 + }
1.113 + return false;
1.114 + }
1.115 +
1.116 + /**
1.117 + * Search for the given method in the given class.
1.118 + *
1.119 + * @param cd Class to search into.
1.120 + * @param method Method to be searched.
1.121 + * @return MethodDoc Method found, null otherwise.
1.122 + */
1.123 + public static MethodDoc findMethod(ClassDoc cd, MethodDoc method) {
1.124 + MethodDoc[] methods = cd.methods();
1.125 + for (int i = 0; i < methods.length; i++) {
1.126 + if (executableMembersEqual(method, methods[i])) {
1.127 + return methods[i];
1.128 +
1.129 + }
1.130 + }
1.131 + return null;
1.132 + }
1.133 +
1.134 + /**
1.135 + * @param member1 the first method to compare.
1.136 + * @param member2 the second method to compare.
1.137 + * @return true if member1 overrides/hides or is overriden/hidden by member2.
1.138 + */
1.139 + public static boolean executableMembersEqual(ExecutableMemberDoc member1,
1.140 + ExecutableMemberDoc member2) {
1.141 + if (! (member1 instanceof MethodDoc && member2 instanceof MethodDoc))
1.142 + return false;
1.143 +
1.144 + MethodDoc method1 = (MethodDoc) member1;
1.145 + MethodDoc method2 = (MethodDoc) member2;
1.146 + if (method1.isStatic() && method2.isStatic()) {
1.147 + Parameter[] targetParams = method1.parameters();
1.148 + Parameter[] currentParams;
1.149 + if (method1.name().equals(method2.name()) &&
1.150 + (currentParams = method2.parameters()).length ==
1.151 + targetParams.length) {
1.152 + int j;
1.153 + for (j = 0; j < targetParams.length; j++) {
1.154 + if (! (targetParams[j].typeName().equals(
1.155 + currentParams[j].typeName()) ||
1.156 + currentParams[j].type() instanceof TypeVariable ||
1.157 + targetParams[j].type() instanceof TypeVariable)) {
1.158 + break;
1.159 + }
1.160 + }
1.161 + if (j == targetParams.length) {
1.162 + return true;
1.163 + }
1.164 + }
1.165 + return false;
1.166 + } else {
1.167 + return method1.overrides(method2) ||
1.168 + method2.overrides(method1) ||
1.169 + member1 == member2;
1.170 + }
1.171 + }
1.172 +
1.173 + /**
1.174 + * According to
1.175 + * <cite>The Java™ Language Specification</cite>,
1.176 + * all the outer classes and static inner classes are core classes.
1.177 + */
1.178 + public static boolean isCoreClass(ClassDoc cd) {
1.179 + return cd.containingClass() == null || cd.isStatic();
1.180 + }
1.181 +
1.182 + public static boolean matches(ProgramElementDoc doc1,
1.183 + ProgramElementDoc doc2) {
1.184 + if (doc1 instanceof ExecutableMemberDoc &&
1.185 + doc2 instanceof ExecutableMemberDoc) {
1.186 + ExecutableMemberDoc ed1 = (ExecutableMemberDoc)doc1;
1.187 + ExecutableMemberDoc ed2 = (ExecutableMemberDoc)doc2;
1.188 + return executableMembersEqual(ed1, ed2);
1.189 + } else {
1.190 + return doc1.name().equals(doc2.name());
1.191 + }
1.192 + }
1.193 +
1.194 + /**
1.195 + * Copy the given directory contents from the source package directory
1.196 + * to the generated documentation directory. For example for a package
1.197 + * java.lang this method find out the source location of the package using
1.198 + * {@link SourcePath} and if given directory is found in the source
1.199 + * directory structure, copy the entire directory, to the generated
1.200 + * documentation hierarchy.
1.201 + *
1.202 + * @param configuration The configuration of the current doclet.
1.203 + * @param path The relative path to the directory to be copied.
1.204 + * @param dir The original directory name to copy from.
1.205 + * @param overwrite Overwrite files if true.
1.206 + */
1.207 + public static void copyDocFiles(Configuration configuration, PackageDoc pd) {
1.208 + copyDocFiles(configuration, DocPath.forPackage(pd).resolve(DocPaths.DOC_FILES));
1.209 + }
1.210 +
1.211 + public static void copyDocFiles(Configuration configuration, DocPath dir) {
1.212 + try {
1.213 + boolean first = true;
1.214 + for (DocFile f : DocFile.list(configuration, StandardLocation.SOURCE_PATH, dir)) {
1.215 + if (!f.isDirectory()) {
1.216 + continue;
1.217 + }
1.218 + DocFile srcdir = f;
1.219 + DocFile destdir = DocFile.createFileForOutput(configuration, dir);
1.220 + if (srcdir.isSameFile(destdir)) {
1.221 + continue;
1.222 + }
1.223 +
1.224 + for (DocFile srcfile: srcdir.list()) {
1.225 + DocFile destfile = destdir.resolve(srcfile.getName());
1.226 + if (srcfile.isFile()) {
1.227 + if (destfile.exists() && !first) {
1.228 + configuration.message.warning((SourcePosition) null,
1.229 + "doclet.Copy_Overwrite_warning",
1.230 + srcfile.getPath(), destdir.getPath());
1.231 + } else {
1.232 + configuration.message.notice(
1.233 + "doclet.Copying_File_0_To_Dir_1",
1.234 + srcfile.getPath(), destdir.getPath());
1.235 + destfile.copyFile(srcfile);
1.236 + }
1.237 + } else if (srcfile.isDirectory()) {
1.238 + if (configuration.copydocfilesubdirs
1.239 + && !configuration.shouldExcludeDocFileDir(srcfile.getName())) {
1.240 + copyDocFiles(configuration, dir.resolve(srcfile.getName()));
1.241 + }
1.242 + }
1.243 + }
1.244 +
1.245 + first = false;
1.246 + }
1.247 + } catch (SecurityException exc) {
1.248 + throw new DocletAbortException(exc);
1.249 + } catch (IOException exc) {
1.250 + throw new DocletAbortException(exc);
1.251 + }
1.252 + }
1.253 +
1.254 + /**
1.255 + * We want the list of types in alphabetical order. However, types are not
1.256 + * comparable. We need a comparator for now.
1.257 + */
1.258 + private static class TypeComparator implements Comparator<Type> {
1.259 + public int compare(Type type1, Type type2) {
1.260 + return type1.qualifiedTypeName().compareToIgnoreCase(
1.261 + type2.qualifiedTypeName());
1.262 + }
1.263 + }
1.264 +
1.265 + /**
1.266 + * For the class return all implemented interfaces including the
1.267 + * superinterfaces of the implementing interfaces, also iterate over for
1.268 + * all the superclasses. For interface return all the extended interfaces
1.269 + * as well as superinterfaces for those extended interfaces.
1.270 + *
1.271 + * @param type type whose implemented or
1.272 + * super interfaces are sought.
1.273 + * @param configuration the current configuration of the doclet.
1.274 + * @param sort if true, return list of interfaces sorted alphabetically.
1.275 + * @return List of all the required interfaces.
1.276 + */
1.277 + public static List<Type> getAllInterfaces(Type type,
1.278 + Configuration configuration, boolean sort) {
1.279 + Map<ClassDoc,Type> results = sort ? new TreeMap<ClassDoc,Type>() : new LinkedHashMap<ClassDoc,Type>();
1.280 + Type[] interfaceTypes = null;
1.281 + Type superType = null;
1.282 + if (type instanceof ParameterizedType) {
1.283 + interfaceTypes = ((ParameterizedType) type).interfaceTypes();
1.284 + superType = ((ParameterizedType) type).superclassType();
1.285 + } else if (type instanceof ClassDoc) {
1.286 + interfaceTypes = ((ClassDoc) type).interfaceTypes();
1.287 + superType = ((ClassDoc) type).superclassType();
1.288 + } else {
1.289 + interfaceTypes = type.asClassDoc().interfaceTypes();
1.290 + superType = type.asClassDoc().superclassType();
1.291 + }
1.292 +
1.293 + for (int i = 0; i < interfaceTypes.length; i++) {
1.294 + Type interfaceType = interfaceTypes[i];
1.295 + ClassDoc interfaceClassDoc = interfaceType.asClassDoc();
1.296 + if (! (interfaceClassDoc.isPublic() ||
1.297 + (configuration == null ||
1.298 + isLinkable(interfaceClassDoc, configuration)))) {
1.299 + continue;
1.300 + }
1.301 + results.put(interfaceClassDoc, interfaceType);
1.302 + List<Type> superInterfaces = getAllInterfaces(interfaceType, configuration, sort);
1.303 + for (Iterator<Type> iter = superInterfaces.iterator(); iter.hasNext(); ) {
1.304 + Type t = iter.next();
1.305 + results.put(t.asClassDoc(), t);
1.306 + }
1.307 + }
1.308 + if (superType == null)
1.309 + return new ArrayList<Type>(results.values());
1.310 + //Try walking the tree.
1.311 + addAllInterfaceTypes(results,
1.312 + superType,
1.313 + interfaceTypesOf(superType),
1.314 + false, configuration);
1.315 + List<Type> resultsList = new ArrayList<Type>(results.values());
1.316 + if (sort) {
1.317 + Collections.sort(resultsList, new TypeComparator());
1.318 + }
1.319 + return resultsList;
1.320 + }
1.321 +
1.322 + private static Type[] interfaceTypesOf(Type type) {
1.323 + if (type instanceof AnnotatedType)
1.324 + type = ((AnnotatedType)type).underlyingType();
1.325 + return type instanceof ClassDoc ?
1.326 + ((ClassDoc)type).interfaceTypes() :
1.327 + ((ParameterizedType)type).interfaceTypes();
1.328 + }
1.329 +
1.330 + public static List<Type> getAllInterfaces(Type type, Configuration configuration) {
1.331 + return getAllInterfaces(type, configuration, true);
1.332 + }
1.333 +
1.334 + private static void findAllInterfaceTypes(Map<ClassDoc,Type> results, ClassDoc c, boolean raw,
1.335 + Configuration configuration) {
1.336 + Type superType = c.superclassType();
1.337 + if (superType == null)
1.338 + return;
1.339 + addAllInterfaceTypes(results, superType,
1.340 + interfaceTypesOf(superType),
1.341 + raw, configuration);
1.342 + }
1.343 +
1.344 + private static void findAllInterfaceTypes(Map<ClassDoc,Type> results, ParameterizedType p,
1.345 + Configuration configuration) {
1.346 + Type superType = p.superclassType();
1.347 + if (superType == null)
1.348 + return;
1.349 + addAllInterfaceTypes(results, superType,
1.350 + interfaceTypesOf(superType),
1.351 + false, configuration);
1.352 + }
1.353 +
1.354 + private static void addAllInterfaceTypes(Map<ClassDoc,Type> results, Type type,
1.355 + Type[] interfaceTypes, boolean raw,
1.356 + Configuration configuration) {
1.357 + for (int i = 0; i < interfaceTypes.length; i++) {
1.358 + Type interfaceType = interfaceTypes[i];
1.359 + ClassDoc interfaceClassDoc = interfaceType.asClassDoc();
1.360 + if (! (interfaceClassDoc.isPublic() ||
1.361 + (configuration != null &&
1.362 + isLinkable(interfaceClassDoc, configuration)))) {
1.363 + continue;
1.364 + }
1.365 + if (raw)
1.366 + interfaceType = interfaceType.asClassDoc();
1.367 + results.put(interfaceClassDoc, interfaceType);
1.368 + List<Type> superInterfaces = getAllInterfaces(interfaceType, configuration);
1.369 + for (Iterator<Type> iter = superInterfaces.iterator(); iter.hasNext(); ) {
1.370 + Type superInterface = iter.next();
1.371 + results.put(superInterface.asClassDoc(), superInterface);
1.372 + }
1.373 + }
1.374 + if (type instanceof AnnotatedType)
1.375 + type = ((AnnotatedType)type).underlyingType();
1.376 +
1.377 + if (type instanceof ParameterizedType)
1.378 + findAllInterfaceTypes(results, (ParameterizedType) type, configuration);
1.379 + else if (((ClassDoc) type).typeParameters().length == 0)
1.380 + findAllInterfaceTypes(results, (ClassDoc) type, raw, configuration);
1.381 + else
1.382 + findAllInterfaceTypes(results, (ClassDoc) type, true, configuration);
1.383 + }
1.384 +
1.385 + /**
1.386 + * Enclose in quotes, used for paths and filenames that contains spaces
1.387 + */
1.388 + public static String quote(String filepath) {
1.389 + return ("\"" + filepath + "\"");
1.390 + }
1.391 +
1.392 + /**
1.393 + * Given a package, return its name.
1.394 + * @param packageDoc the package to check.
1.395 + * @return the name of the given package.
1.396 + */
1.397 + public static String getPackageName(PackageDoc packageDoc) {
1.398 + return packageDoc == null || packageDoc.name().length() == 0 ?
1.399 + DocletConstants.DEFAULT_PACKAGE_NAME : packageDoc.name();
1.400 + }
1.401 +
1.402 + /**
1.403 + * Given a package, return its file name without the extension.
1.404 + * @param packageDoc the package to check.
1.405 + * @return the file name of the given package.
1.406 + */
1.407 + public static String getPackageFileHeadName(PackageDoc packageDoc) {
1.408 + return packageDoc == null || packageDoc.name().length() == 0 ?
1.409 + DocletConstants.DEFAULT_PACKAGE_FILE_NAME : packageDoc.name();
1.410 + }
1.411 +
1.412 + /**
1.413 + * Given a string, replace all occurrences of 'newStr' with 'oldStr'.
1.414 + * @param originalStr the string to modify.
1.415 + * @param oldStr the string to replace.
1.416 + * @param newStr the string to insert in place of the old string.
1.417 + */
1.418 + public static String replaceText(String originalStr, String oldStr,
1.419 + String newStr) {
1.420 + if (oldStr == null || newStr == null || oldStr.equals(newStr)) {
1.421 + return originalStr;
1.422 + }
1.423 + return originalStr.replace(oldStr, newStr);
1.424 + }
1.425 +
1.426 + /**
1.427 + * Given an annotation, return true if it should be documented and false
1.428 + * otherwise.
1.429 + *
1.430 + * @param annotationDoc the annotation to check.
1.431 + *
1.432 + * @return true return true if it should be documented and false otherwise.
1.433 + */
1.434 + public static boolean isDocumentedAnnotation(AnnotationTypeDoc annotationDoc) {
1.435 + AnnotationDesc[] annotationDescList = annotationDoc.annotations();
1.436 + for (int i = 0; i < annotationDescList.length; i++) {
1.437 + if (annotationDescList[i].annotationType().qualifiedName().equals(
1.438 + java.lang.annotation.Documented.class.getName())){
1.439 + return true;
1.440 + }
1.441 + }
1.442 + return false;
1.443 + }
1.444 +
1.445 + private static boolean isDeclarationTarget(AnnotationDesc targetAnno) {
1.446 + // The error recovery steps here are analogous to TypeAnnotations
1.447 + ElementValuePair[] elems = targetAnno.elementValues();
1.448 + if (elems == null
1.449 + || elems.length != 1
1.450 + || !"value".equals(elems[0].element().name())
1.451 + || !(elems[0].value().value() instanceof AnnotationValue[]))
1.452 + return true; // error recovery
1.453 +
1.454 + AnnotationValue[] values = (AnnotationValue[])elems[0].value().value();
1.455 + for (int i = 0; i < values.length; i++) {
1.456 + Object value = values[i].value();
1.457 + if (!(value instanceof FieldDoc))
1.458 + return true; // error recovery
1.459 +
1.460 + FieldDoc eValue = (FieldDoc)value;
1.461 + if (Util.isJava5DeclarationElementType(eValue)) {
1.462 + return true;
1.463 + }
1.464 + }
1.465 +
1.466 + return false;
1.467 + }
1.468 +
1.469 + /**
1.470 + * Returns true if the {@code annotationDoc} is to be treated
1.471 + * as a declaration annotation, when targeting the
1.472 + * {@code elemType} element type.
1.473 + *
1.474 + * @param annotationDoc the annotationDoc to check
1.475 + * @param elemType the targeted elemType
1.476 + * @return true if annotationDoc is a declaration annotation
1.477 + */
1.478 + public static boolean isDeclarationAnnotation(AnnotationTypeDoc annotationDoc,
1.479 + boolean isJava5DeclarationLocation) {
1.480 + if (!isJava5DeclarationLocation)
1.481 + return false;
1.482 + AnnotationDesc[] annotationDescList = annotationDoc.annotations();
1.483 + // Annotations with no target are treated as declaration as well
1.484 + if (annotationDescList.length==0)
1.485 + return true;
1.486 + for (int i = 0; i < annotationDescList.length; i++) {
1.487 + if (annotationDescList[i].annotationType().qualifiedName().equals(
1.488 + java.lang.annotation.Target.class.getName())) {
1.489 + if (isDeclarationTarget(annotationDescList[i]))
1.490 + return true;
1.491 + }
1.492 + }
1.493 + return false;
1.494 + }
1.495 +
1.496 + /**
1.497 + * Return true if this class is linkable and false if we can't link to the
1.498 + * desired class.
1.499 + * <br>
1.500 + * <b>NOTE:</b> You can only link to external classes if they are public or
1.501 + * protected.
1.502 + *
1.503 + * @param classDoc the class to check.
1.504 + * @param configuration the current configuration of the doclet.
1.505 + *
1.506 + * @return true if this class is linkable and false if we can't link to the
1.507 + * desired class.
1.508 + */
1.509 + public static boolean isLinkable(ClassDoc classDoc,
1.510 + Configuration configuration) {
1.511 + return
1.512 + ((classDoc.isIncluded() && configuration.isGeneratedDoc(classDoc))) ||
1.513 + (configuration.extern.isExternal(classDoc) &&
1.514 + (classDoc.isPublic() || classDoc.isProtected()));
1.515 + }
1.516 +
1.517 + /**
1.518 + * Given a class, return the closest visible super class.
1.519 + *
1.520 + * @param classDoc the class we are searching the parent for.
1.521 + * @param configuration the current configuration of the doclet.
1.522 + * @return the closest visible super class. Return null if it cannot
1.523 + * be found (i.e. classDoc is java.lang.Object).
1.524 + */
1.525 + public static Type getFirstVisibleSuperClass(ClassDoc classDoc,
1.526 + Configuration configuration) {
1.527 + if (classDoc == null) {
1.528 + return null;
1.529 + }
1.530 + Type sup = classDoc.superclassType();
1.531 + ClassDoc supClassDoc = classDoc.superclass();
1.532 + while (sup != null &&
1.533 + (! (supClassDoc.isPublic() ||
1.534 + isLinkable(supClassDoc, configuration))) ) {
1.535 + if (supClassDoc.superclass().qualifiedName().equals(supClassDoc.qualifiedName()))
1.536 + break;
1.537 + sup = supClassDoc.superclassType();
1.538 + supClassDoc = supClassDoc.superclass();
1.539 + }
1.540 + if (classDoc.equals(supClassDoc)) {
1.541 + return null;
1.542 + }
1.543 + return sup;
1.544 + }
1.545 +
1.546 + /**
1.547 + * Given a class, return the closest visible super class.
1.548 + *
1.549 + * @param classDoc the class we are searching the parent for.
1.550 + * @param configuration the current configuration of the doclet.
1.551 + * @return the closest visible super class. Return null if it cannot
1.552 + * be found (i.e. classDoc is java.lang.Object).
1.553 + */
1.554 + public static ClassDoc getFirstVisibleSuperClassCD(ClassDoc classDoc,
1.555 + Configuration configuration) {
1.556 + if (classDoc == null) {
1.557 + return null;
1.558 + }
1.559 + ClassDoc supClassDoc = classDoc.superclass();
1.560 + while (supClassDoc != null &&
1.561 + (! (supClassDoc.isPublic() ||
1.562 + isLinkable(supClassDoc, configuration))) ) {
1.563 + supClassDoc = supClassDoc.superclass();
1.564 + }
1.565 + if (classDoc.equals(supClassDoc)) {
1.566 + return null;
1.567 + }
1.568 + return supClassDoc;
1.569 + }
1.570 +
1.571 + /**
1.572 + * Given a ClassDoc, return the name of its type (Class, Interface, etc.).
1.573 + *
1.574 + * @param cd the ClassDoc to check.
1.575 + * @param lowerCaseOnly true if you want the name returned in lower case.
1.576 + * If false, the first letter of the name is capitalized.
1.577 + * @return
1.578 + */
1.579 + public static String getTypeName(Configuration config,
1.580 + ClassDoc cd, boolean lowerCaseOnly) {
1.581 + String typeName = "";
1.582 + if (cd.isOrdinaryClass()) {
1.583 + typeName = "doclet.Class";
1.584 + } else if (cd.isInterface()) {
1.585 + typeName = "doclet.Interface";
1.586 + } else if (cd.isException()) {
1.587 + typeName = "doclet.Exception";
1.588 + } else if (cd.isError()) {
1.589 + typeName = "doclet.Error";
1.590 + } else if (cd.isAnnotationType()) {
1.591 + typeName = "doclet.AnnotationType";
1.592 + } else if (cd.isEnum()) {
1.593 + typeName = "doclet.Enum";
1.594 + }
1.595 + return config.getText(
1.596 + lowerCaseOnly ? StringUtils.toLowerCase(typeName) : typeName);
1.597 + }
1.598 +
1.599 + /**
1.600 + * Replace all tabs in a string with the appropriate number of spaces.
1.601 + * The string may be a multi-line string.
1.602 + * @param configuration the doclet configuration defining the setting for the
1.603 + * tab length.
1.604 + * @param text the text for which the tabs should be expanded
1.605 + * @return the text with all tabs expanded
1.606 + */
1.607 + public static String replaceTabs(Configuration configuration, String text) {
1.608 + if (text.indexOf("\t") == -1)
1.609 + return text;
1.610 +
1.611 + final int tabLength = configuration.sourcetab;
1.612 + final String whitespace = configuration.tabSpaces;
1.613 + final int textLength = text.length();
1.614 + StringBuilder result = new StringBuilder(textLength);
1.615 + int pos = 0;
1.616 + int lineLength = 0;
1.617 + for (int i = 0; i < textLength; i++) {
1.618 + char ch = text.charAt(i);
1.619 + switch (ch) {
1.620 + case '\n': case '\r':
1.621 + lineLength = 0;
1.622 + break;
1.623 + case '\t':
1.624 + result.append(text, pos, i);
1.625 + int spaceCount = tabLength - lineLength % tabLength;
1.626 + result.append(whitespace, 0, spaceCount);
1.627 + lineLength += spaceCount;
1.628 + pos = i + 1;
1.629 + break;
1.630 + default:
1.631 + lineLength++;
1.632 + }
1.633 + }
1.634 + result.append(text, pos, textLength);
1.635 + return result.toString();
1.636 + }
1.637 +
1.638 + public static String normalizeNewlines(String text) {
1.639 + StringBuilder sb = new StringBuilder();
1.640 + final int textLength = text.length();
1.641 + final String NL = DocletConstants.NL;
1.642 + int pos = 0;
1.643 + for (int i = 0; i < textLength; i++) {
1.644 + char ch = text.charAt(i);
1.645 + switch (ch) {
1.646 + case '\n':
1.647 + sb.append(text, pos, i);
1.648 + sb.append(NL);
1.649 + pos = i + 1;
1.650 + break;
1.651 + case '\r':
1.652 + sb.append(text, pos, i);
1.653 + sb.append(NL);
1.654 + if (i + 1 < textLength && text.charAt(i + 1) == '\n')
1.655 + i++;
1.656 + pos = i + 1;
1.657 + break;
1.658 + }
1.659 + }
1.660 + sb.append(text, pos, textLength);
1.661 + return sb.toString();
1.662 + }
1.663 +
1.664 + /**
1.665 + * The documentation for values() and valueOf() in Enums are set by the
1.666 + * doclet.
1.667 + */
1.668 + public static void setEnumDocumentation(Configuration configuration,
1.669 + ClassDoc classDoc) {
1.670 + MethodDoc[] methods = classDoc.methods();
1.671 + for (int j = 0; j < methods.length; j++) {
1.672 + MethodDoc currentMethod = methods[j];
1.673 + if (currentMethod.name().equals("values") &&
1.674 + currentMethod.parameters().length == 0) {
1.675 + StringBuilder sb = new StringBuilder();
1.676 + sb.append(configuration.getText("doclet.enum_values_doc.main", classDoc.name()));
1.677 + sb.append("\n@return ");
1.678 + sb.append(configuration.getText("doclet.enum_values_doc.return"));
1.679 + currentMethod.setRawCommentText(sb.toString());
1.680 + } else if (currentMethod.name().equals("valueOf") &&
1.681 + currentMethod.parameters().length == 1) {
1.682 + Type paramType = currentMethod.parameters()[0].type();
1.683 + if (paramType != null &&
1.684 + paramType.qualifiedTypeName().equals(String.class.getName())) {
1.685 + StringBuilder sb = new StringBuilder();
1.686 + sb.append(configuration.getText("doclet.enum_valueof_doc.main", classDoc.name()));
1.687 + sb.append("\n@param name ");
1.688 + sb.append(configuration.getText("doclet.enum_valueof_doc.param_name"));
1.689 + sb.append("\n@return ");
1.690 + sb.append(configuration.getText("doclet.enum_valueof_doc.return"));
1.691 + sb.append("\n@throws IllegalArgumentException ");
1.692 + sb.append(configuration.getText("doclet.enum_valueof_doc.throws_ila"));
1.693 + sb.append("\n@throws NullPointerException ");
1.694 + sb.append(configuration.getText("doclet.enum_valueof_doc.throws_npe"));
1.695 + currentMethod.setRawCommentText(sb.toString());
1.696 + }
1.697 + }
1.698 + }
1.699 + }
1.700 +
1.701 + /**
1.702 + * Return true if the given Doc is deprecated.
1.703 + *
1.704 + * @param doc the Doc to check.
1.705 + * @return true if the given Doc is deprecated.
1.706 + */
1.707 + public static boolean isDeprecated(Doc doc) {
1.708 + if (doc.tags("deprecated").length > 0) {
1.709 + return true;
1.710 + }
1.711 + AnnotationDesc[] annotationDescList;
1.712 + if (doc instanceof PackageDoc)
1.713 + annotationDescList = ((PackageDoc)doc).annotations();
1.714 + else
1.715 + annotationDescList = ((ProgramElementDoc)doc).annotations();
1.716 + for (int i = 0; i < annotationDescList.length; i++) {
1.717 + if (annotationDescList[i].annotationType().qualifiedName().equals(
1.718 + java.lang.Deprecated.class.getName())){
1.719 + return true;
1.720 + }
1.721 + }
1.722 + return false;
1.723 + }
1.724 +
1.725 + /**
1.726 + * A convenience method to get property name from the name of the
1.727 + * getter or setter method.
1.728 + * @param name name of the getter or setter method.
1.729 + * @return the name of the property of the given setter of getter.
1.730 + */
1.731 + public static String propertyNameFromMethodName(Configuration configuration, String name) {
1.732 + String propertyName = null;
1.733 + if (name.startsWith("get") || name.startsWith("set")) {
1.734 + propertyName = name.substring(3);
1.735 + } else if (name.startsWith("is")) {
1.736 + propertyName = name.substring(2);
1.737 + }
1.738 + if ((propertyName == null) || propertyName.isEmpty()){
1.739 + return "";
1.740 + }
1.741 + return propertyName.substring(0, 1).toLowerCase(configuration.getLocale())
1.742 + + propertyName.substring(1);
1.743 + }
1.744 +
1.745 + /**
1.746 + * In case of JavaFX mode on, filters out classes that are private,
1.747 + * package private or having the @treatAsPrivate annotation. Those are not
1.748 + * documented in JavaFX mode.
1.749 + *
1.750 + * @param classes array of classes to be filtered.
1.751 + * @param javafx set to true if in JavaFX mode.
1.752 + * @return list of filtered classes.
1.753 + */
1.754 + public static ClassDoc[] filterOutPrivateClasses(final ClassDoc[] classes,
1.755 + boolean javafx) {
1.756 + if (!javafx) {
1.757 + return classes;
1.758 + }
1.759 + final List<ClassDoc> filteredOutClasses =
1.760 + new ArrayList<ClassDoc>(classes.length);
1.761 + for (ClassDoc classDoc : classes) {
1.762 + if (classDoc.isPrivate() || classDoc.isPackagePrivate()) {
1.763 + continue;
1.764 + }
1.765 + Tag[] aspTags = classDoc.tags("treatAsPrivate");
1.766 + if (aspTags != null && aspTags.length > 0) {
1.767 + continue;
1.768 + }
1.769 + filteredOutClasses.add(classDoc);
1.770 + }
1.771 +
1.772 + return filteredOutClasses.toArray(new ClassDoc[0]);
1.773 + }
1.774 +
1.775 + /**
1.776 + * Test whether the given FieldDoc is one of the declaration annotation ElementTypes
1.777 + * defined in Java 5.
1.778 + * Instead of testing for one of the new enum constants added in Java 8, test for
1.779 + * the old constants. This prevents bootstrapping problems.
1.780 + *
1.781 + * @param elt The FieldDoc to test
1.782 + * @return true, iff the given ElementType is one of the constants defined in Java 5
1.783 + * @since 1.8
1.784 + */
1.785 + public static boolean isJava5DeclarationElementType(FieldDoc elt) {
1.786 + return elt.name().contentEquals(ElementType.ANNOTATION_TYPE.name()) ||
1.787 + elt.name().contentEquals(ElementType.CONSTRUCTOR.name()) ||
1.788 + elt.name().contentEquals(ElementType.FIELD.name()) ||
1.789 + elt.name().contentEquals(ElementType.LOCAL_VARIABLE.name()) ||
1.790 + elt.name().contentEquals(ElementType.METHOD.name()) ||
1.791 + elt.name().contentEquals(ElementType.PACKAGE.name()) ||
1.792 + elt.name().contentEquals(ElementType.PARAMETER.name()) ||
1.793 + elt.name().contentEquals(ElementType.TYPE.name());
1.794 + }
1.795 +}
