1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/MemberSummaryBuilder.java Sat Dec 01 00:00:00 2007 +0000
1.3 @@ -0,0 +1,369 @@
1.4 +/*
1.5 + * Copyright 2003-2004 Sun Microsystems, Inc. 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. Sun designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
1.25 + * CA 95054 USA or visit www.sun.com if you need additional information or
1.26 + * have any questions.
1.27 + */
1.28 +
1.29 +package com.sun.tools.doclets.internal.toolkit.builders;
1.30 +
1.31 +import com.sun.tools.doclets.internal.toolkit.util.*;
1.32 +import com.sun.tools.doclets.internal.toolkit.*;
1.33 +import com.sun.javadoc.*;
1.34 +import java.util.*;
1.35 +import java.lang.reflect.*;
1.36 +
1.37 +/**
1.38 + * Builds the member summary.
1.39 + *
1.40 + * This code is not part of an API.
1.41 + * It is implementation that is subject to change.
1.42 + * Do not use it as an API
1.43 + *
1.44 + * @author Jamie Ho
1.45 + * @since 1.5
1.46 + */
1.47 +public class MemberSummaryBuilder extends AbstractMemberBuilder {
1.48 +
1.49 + /**
1.50 + * The XML root for this builder.
1.51 + */
1.52 + public static final String NAME = "MemberSummary";
1.53 +
1.54 + /**
1.55 + * The visible members for the given class.
1.56 + */
1.57 + private VisibleMemberMap[] visibleMemberMaps;
1.58 +
1.59 + /**
1.60 + * The member summary writers for the given class.
1.61 + */
1.62 + private MemberSummaryWriter[] memberSummaryWriters;
1.63 +
1.64 + /**
1.65 + * The type being documented.
1.66 + */
1.67 + private ClassDoc classDoc;
1.68 +
1.69 + private MemberSummaryBuilder(Configuration configuration) {
1.70 + super(configuration);
1.71 + }
1.72 +
1.73 + /**
1.74 + * Construct a new MemberSummaryBuilder.
1.75 + *
1.76 + * @param classWriter the writer for the class whose members are being
1.77 + * summarized.
1.78 + * @param configuration the current configuration of the doclet.
1.79 + */
1.80 + public static MemberSummaryBuilder getInstance(
1.81 + ClassWriter classWriter, Configuration configuration)
1.82 + throws Exception {
1.83 + MemberSummaryBuilder builder = new MemberSummaryBuilder(configuration);
1.84 + builder.classDoc = classWriter.getClassDoc();
1.85 + builder.init(classWriter);
1.86 + return builder;
1.87 + }
1.88 +
1.89 + /**
1.90 + * Construct a new MemberSummaryBuilder.
1.91 + *
1.92 + * @param annotationTypeWriter the writer for the class whose members are
1.93 + * being summarized.
1.94 + * @param configuration the current configuration of the doclet.
1.95 + */
1.96 + public static MemberSummaryBuilder getInstance(
1.97 + AnnotationTypeWriter annotationTypeWriter, Configuration configuration)
1.98 + throws Exception {
1.99 + MemberSummaryBuilder builder = new MemberSummaryBuilder(configuration);
1.100 + builder.classDoc = annotationTypeWriter.getAnnotationTypeDoc();
1.101 + builder.init(annotationTypeWriter);
1.102 + return builder;
1.103 + }
1.104 +
1.105 + private void init(Object writer) throws Exception {
1.106 + visibleMemberMaps =
1.107 + new VisibleMemberMap[VisibleMemberMap.NUM_MEMBER_TYPES];
1.108 + for (int i = 0; i < VisibleMemberMap.NUM_MEMBER_TYPES; i++) {
1.109 + visibleMemberMaps[i] =
1.110 + new VisibleMemberMap(
1.111 + classDoc,
1.112 + i,
1.113 + configuration.nodeprecated);
1.114 + }
1.115 + memberSummaryWriters =
1.116 + new MemberSummaryWriter[VisibleMemberMap.NUM_MEMBER_TYPES];
1.117 + for (int i = 0; i < VisibleMemberMap.NUM_MEMBER_TYPES; i++) {
1.118 + if (classDoc.isAnnotationType()) {
1.119 + memberSummaryWriters[i] =
1.120 + visibleMemberMaps[i].noVisibleMembers()?
1.121 + null :
1.122 + configuration.getWriterFactory().getMemberSummaryWriter(
1.123 + (AnnotationTypeWriter) writer, i);
1.124 + } else {
1.125 + memberSummaryWriters[i] =
1.126 + visibleMemberMaps[i].noVisibleMembers()?
1.127 + null :
1.128 + configuration.getWriterFactory().getMemberSummaryWriter(
1.129 + (ClassWriter) writer, i);
1.130 + }
1.131 + }
1.132 +
1.133 + }
1.134 +
1.135 + /**
1.136 + * {@inheritDoc}
1.137 + */
1.138 + public String getName() {
1.139 + return NAME;
1.140 + }
1.141 +
1.142 + /**
1.143 + * Return the specified visible member map.
1.144 + *
1.145 + * @param type the type of visible member map to return.
1.146 + * @return the specified visible member map.
1.147 + * @throws ArrayIndexOutOfBoundsException when the type is invalid.
1.148 + * @see VisibleMemberMap
1.149 + */
1.150 + public VisibleMemberMap getVisibleMemberMap(int type) {
1.151 + return visibleMemberMaps[type];
1.152 + }
1.153 +
1.154 + /**
1.155 + * Return the specified member summary writer.
1.156 + *
1.157 + * @param type the type of member summary writer to return.
1.158 + * @return the specified member summary writer.
1.159 + * @throws ArrayIndexOutOfBoundsException when the type is invalid.
1.160 + * @see VisibleMemberMap
1.161 + */
1.162 + public MemberSummaryWriter getMemberSummaryWriter(int type) {
1.163 + return memberSummaryWriters[type];
1.164 + }
1.165 +
1.166 + /**
1.167 + * Returns a list of methods that will be documented for the given class.
1.168 + * This information can be used for doclet specific documentation
1.169 + * generation.
1.170 + *
1.171 + * @param classDoc the {@link ClassDoc} we want to check.
1.172 + * @param type the type of members to return.
1.173 + * @return a list of methods that will be documented.
1.174 + * @see VisibleMemberMap
1.175 + */
1.176 + public List members(int type) {
1.177 + return visibleMemberMaps[type].getLeafClassMembers(configuration);
1.178 + }
1.179 +
1.180 + /**
1.181 + * {@inheritDoc}
1.182 + */
1.183 + public void invokeMethod(
1.184 + String methodName,
1.185 + Class[] paramClasses,
1.186 + Object[] params)
1.187 + throws Exception {
1.188 + if (DEBUG) {
1.189 + configuration.root.printError(
1.190 + "DEBUG: " + this.getClass().getName() + "." + methodName);
1.191 + }
1.192 + Method method = this.getClass().getMethod(methodName, paramClasses);
1.193 + method.invoke(this, params);
1.194 + }
1.195 +
1.196 + /**
1.197 + * Return true it there are any members to summarize.
1.198 + *
1.199 + * @return true if there are any members to summarize.
1.200 + */
1.201 + public boolean hasMembersToDocument() {
1.202 + if (classDoc instanceof AnnotationTypeDoc) {
1.203 + return ((AnnotationTypeDoc) classDoc).elements().length > 0;
1.204 + }
1.205 + for (int i = 0; i < VisibleMemberMap.NUM_MEMBER_TYPES; i++) {
1.206 + VisibleMemberMap members = visibleMemberMaps[i];
1.207 + if (!members.noVisibleMembers()) {
1.208 + return true;
1.209 + }
1.210 + }
1.211 + return false;
1.212 + }
1.213 +
1.214 + /**
1.215 + * Build the summary for the enum constants.
1.216 + */
1.217 + public void buildEnumConstantsSummary() {
1.218 + buildSummary(
1.219 + memberSummaryWriters[VisibleMemberMap.ENUM_CONSTANTS],
1.220 + visibleMemberMaps[VisibleMemberMap.ENUM_CONSTANTS]);
1.221 + }
1.222 +
1.223 + /**
1.224 + * Build the summary for the optional members.
1.225 + */
1.226 + public void buildAnnotationTypeOptionalMemberSummary() {
1.227 + buildSummary(
1.228 + memberSummaryWriters[VisibleMemberMap.ANNOTATION_TYPE_MEMBER_OPTIONAL],
1.229 + visibleMemberMaps[VisibleMemberMap.ANNOTATION_TYPE_MEMBER_OPTIONAL]);
1.230 + }
1.231 +
1.232 + /**
1.233 + * Build the summary for the optional members.
1.234 + */
1.235 + public void buildAnnotationTypeRequiredMemberSummary() {
1.236 + buildSummary(
1.237 + memberSummaryWriters[VisibleMemberMap.ANNOTATION_TYPE_MEMBER_REQUIRED],
1.238 + visibleMemberMaps[VisibleMemberMap.ANNOTATION_TYPE_MEMBER_REQUIRED]);
1.239 + }
1.240 +
1.241 + /**
1.242 + * Build the summary for the fields.
1.243 + */
1.244 + public void buildFieldsSummary() {
1.245 + buildSummary(
1.246 + memberSummaryWriters[VisibleMemberMap.FIELDS],
1.247 + visibleMemberMaps[VisibleMemberMap.FIELDS]);
1.248 + }
1.249 +
1.250 + /**
1.251 + * Build the inherited summary for the fields.
1.252 + */
1.253 + public void buildFieldsInheritedSummary() {
1.254 + buildInheritedSummary(
1.255 + memberSummaryWriters[VisibleMemberMap.FIELDS],
1.256 + visibleMemberMaps[VisibleMemberMap.FIELDS]);
1.257 + }
1.258 +
1.259 + /**
1.260 + * Build the summary for the nested classes.
1.261 + */
1.262 + public void buildNestedClassesSummary() {
1.263 + buildSummary(
1.264 + memberSummaryWriters[VisibleMemberMap.INNERCLASSES],
1.265 + visibleMemberMaps[VisibleMemberMap.INNERCLASSES]);
1.266 + }
1.267 +
1.268 + /**
1.269 + * Build the inherited summary for the nested classes.
1.270 + */
1.271 + public void buildNestedClassesInheritedSummary() {
1.272 + buildInheritedSummary(
1.273 + memberSummaryWriters[VisibleMemberMap.INNERCLASSES],
1.274 + visibleMemberMaps[VisibleMemberMap.INNERCLASSES]);
1.275 + }
1.276 +
1.277 + /**
1.278 + * Build the method summary.
1.279 + */
1.280 + public void buildMethodsSummary() {
1.281 + buildSummary(
1.282 + memberSummaryWriters[VisibleMemberMap.METHODS],
1.283 + visibleMemberMaps[VisibleMemberMap.METHODS]);
1.284 + }
1.285 +
1.286 + /**
1.287 + * Build the inherited method summary.
1.288 + */
1.289 + public void buildMethodsInheritedSummary() {
1.290 + buildInheritedSummary(
1.291 + memberSummaryWriters[VisibleMemberMap.METHODS],
1.292 + visibleMemberMaps[VisibleMemberMap.METHODS]);
1.293 + }
1.294 +
1.295 + /**
1.296 + * Build the constructor summary.
1.297 + */
1.298 + public void buildConstructorsSummary() {
1.299 + buildSummary(
1.300 + memberSummaryWriters[VisibleMemberMap.CONSTRUCTORS],
1.301 + visibleMemberMaps[VisibleMemberMap.CONSTRUCTORS]);
1.302 + }
1.303 +
1.304 + /**
1.305 + * Build the member summary for the given members.
1.306 + *
1.307 + * @param writer the summary writer to write the output.
1.308 + * @param visibleMemberMap the given members to summarize.
1.309 + */
1.310 + private void buildSummary(MemberSummaryWriter writer,
1.311 + VisibleMemberMap visibleMemberMap) {
1.312 + List members = new ArrayList(visibleMemberMap.getLeafClassMembers(
1.313 + configuration));
1.314 + if (members.size() > 0) {
1.315 + Collections.sort(members);
1.316 + writer.writeMemberSummaryHeader(classDoc);
1.317 + for (int i = 0; i < members.size(); i++) {
1.318 + ProgramElementDoc member = (ProgramElementDoc) members.get(i);
1.319 + Tag[] firstSentenceTags = member.firstSentenceTags();
1.320 + if (member instanceof MethodDoc && firstSentenceTags.length == 0) {
1.321 + //Inherit comments from overriden or implemented method if
1.322 + //necessary.
1.323 + DocFinder.Output inheritedDoc =
1.324 + DocFinder.search(new DocFinder.Input((MethodDoc) member));
1.325 + if (inheritedDoc.holder != null &&
1.326 + inheritedDoc.holder.firstSentenceTags().length > 0) {
1.327 + firstSentenceTags = inheritedDoc.holder.firstSentenceTags();
1.328 + }
1.329 + }
1.330 + writer.writeMemberSummary(classDoc, member, firstSentenceTags,
1.331 + i == 0, i == members.size() - 1);
1.332 + }
1.333 + writer.writeMemberSummaryFooter(classDoc);
1.334 + }
1.335 + }
1.336 +
1.337 + /**
1.338 + * Build the inherited member summary for the given methods.
1.339 + *
1.340 + * @param writer the writer for this member summary.
1.341 + * @param visibleMemberMap the map for the members to document.
1.342 + */
1.343 + private void buildInheritedSummary(MemberSummaryWriter writer,
1.344 + VisibleMemberMap visibleMemberMap) {
1.345 + for (Iterator iter = visibleMemberMap.getVisibleClassesList().iterator();
1.346 + iter.hasNext();) {
1.347 + ClassDoc inhclass = (ClassDoc) (iter.next());
1.348 + if (! (inhclass.isPublic() ||
1.349 + Util.isLinkable(inhclass, configuration))) {
1.350 + continue;
1.351 + }
1.352 + if (inhclass == classDoc) {
1.353 + continue;
1.354 + }
1.355 + List inhmembers = visibleMemberMap.getMembersFor(inhclass);
1.356 + if (inhmembers.size() > 0) {
1.357 + Collections.sort(inhmembers);
1.358 + writer.writeInheritedMemberSummaryHeader(inhclass);
1.359 + for (int j = 0; j < inhmembers.size(); ++j) {
1.360 + writer.writeInheritedMemberSummary(
1.361 + inhclass.isPackagePrivate() &&
1.362 + ! Util.isLinkable(inhclass, configuration) ?
1.363 + classDoc : inhclass,
1.364 + (ProgramElementDoc) inhmembers.get(j),
1.365 + j == 0,
1.366 + j == inhmembers.size() - 1);
1.367 + }
1.368 + writer.writeInheritedMemberSummaryFooter(inhclass);
1.369 + }
1.370 + }
1.371 + }
1.372 +}
