1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/classes/com/sun/tools/doclets/formats/html/AbstractMemberWriter.java Sat Dec 01 00:00:00 2007 +0000
1.3 @@ -0,0 +1,427 @@
1.4 +/*
1.5 + * Copyright 1997-2006 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.formats.html;
1.30 +
1.31 +import com.sun.tools.doclets.internal.toolkit.util.*;
1.32 +import com.sun.tools.doclets.internal.toolkit.taglets.*;
1.33 +
1.34 +import com.sun.javadoc.*;
1.35 +import java.util.*;
1.36 +import java.lang.reflect.Modifier;
1.37 +
1.38 +/**
1.39 + * The base class for member writers.
1.40 + *
1.41 + * @author Robert Field
1.42 + * @author Atul M Dambalkar
1.43 + * @author Jamie Ho (Re-write)
1.44 + */
1.45 +public abstract class AbstractMemberWriter {
1.46 +
1.47 + protected boolean printedSummaryHeader = false;
1.48 + protected final SubWriterHolderWriter writer;
1.49 + protected final ClassDoc classdoc;
1.50 + public final boolean nodepr;
1.51 +
1.52 + public AbstractMemberWriter(SubWriterHolderWriter writer,
1.53 + ClassDoc classdoc) {
1.54 + this.writer = writer;
1.55 + this.nodepr = configuration().nodeprecated;
1.56 + this.classdoc = classdoc;
1.57 + }
1.58 +
1.59 + public AbstractMemberWriter(SubWriterHolderWriter writer) {
1.60 + this(writer, null);
1.61 + }
1.62 +
1.63 + /*** abstracts ***/
1.64 +
1.65 + public abstract void printSummaryLabel(ClassDoc cd);
1.66 +
1.67 + public abstract void printInheritedSummaryLabel(ClassDoc cd);
1.68 +
1.69 + public abstract void printSummaryAnchor(ClassDoc cd);
1.70 +
1.71 + public abstract void printInheritedSummaryAnchor(ClassDoc cd);
1.72 +
1.73 + protected abstract void printSummaryType(ProgramElementDoc member);
1.74 +
1.75 + protected void writeSummaryLink(ClassDoc cd, ProgramElementDoc member) {
1.76 + writeSummaryLink(LinkInfoImpl.CONTEXT_MEMBER, cd, member);
1.77 + }
1.78 +
1.79 + protected abstract void writeSummaryLink(int context,
1.80 + ClassDoc cd,
1.81 + ProgramElementDoc member);
1.82 +
1.83 + protected abstract void writeInheritedSummaryLink(ClassDoc cd,
1.84 + ProgramElementDoc member);
1.85 +
1.86 + protected abstract void writeDeprecatedLink(ProgramElementDoc member);
1.87 +
1.88 + protected abstract void printNavSummaryLink(ClassDoc cd, boolean link);
1.89 +
1.90 + protected abstract void printNavDetailLink(boolean link);
1.91 +
1.92 + /*** ***/
1.93 +
1.94 + protected void print(String str) {
1.95 + writer.print(str);
1.96 + writer.displayLength += str.length();
1.97 + }
1.98 +
1.99 + protected void print(char ch) {
1.100 + writer.print(ch);
1.101 + writer.displayLength++;
1.102 + }
1.103 +
1.104 + protected void bold(String str) {
1.105 + writer.bold(str);
1.106 + writer.displayLength += str.length();
1.107 + }
1.108 +
1.109 + /**
1.110 + * Return a string describing the access modifier flags.
1.111 + * Don't include native or synchronized.
1.112 + *
1.113 + * The modifier names are returned in canonical order, as
1.114 + * specified by <em>The Java Language Specification</em>.
1.115 + */
1.116 + protected String modifierString(MemberDoc member) {
1.117 + int ms = member.modifierSpecifier();
1.118 + int no = Modifier.NATIVE | Modifier.SYNCHRONIZED;
1.119 + return Modifier.toString(ms & ~no);
1.120 + }
1.121 +
1.122 + protected String typeString(MemberDoc member) {
1.123 + String type = "";
1.124 + if (member instanceof MethodDoc) {
1.125 + type = ((MethodDoc)member).returnType().toString();
1.126 + } else if (member instanceof FieldDoc) {
1.127 + type = ((FieldDoc)member).type().toString();
1.128 + }
1.129 + return type;
1.130 + }
1.131 +
1.132 + protected void printModifiers(MemberDoc member) {
1.133 + String mod = modifierString(member);
1.134 + // According to JLS, we should not be showing public modifier for
1.135 + // interface methods.
1.136 + if ((member.isField() || member.isMethod()) &&
1.137 + writer instanceof ClassWriterImpl &&
1.138 + ((ClassWriterImpl) writer).getClassDoc().isInterface()) {
1.139 + mod = Util.replaceText(mod, "public", "").trim();
1.140 + }
1.141 + if(mod.length() > 0) {
1.142 + print(mod);
1.143 + print(' ');
1.144 + }
1.145 + }
1.146 +
1.147 + protected String makeSpace(int len) {
1.148 + if (len <= 0) {
1.149 + return "";
1.150 + }
1.151 + StringBuffer sb = new StringBuffer(len);
1.152 + for(int i = 0; i < len; i++) {
1.153 + sb.append(' ');
1.154 + }
1.155 + return sb.toString();
1.156 + }
1.157 +
1.158 + /**
1.159 + * Print 'static' if static and type link.
1.160 + */
1.161 + protected void printStaticAndType(boolean isStatic, Type type) {
1.162 + writer.printTypeSummaryHeader();
1.163 + if (isStatic) {
1.164 + print("static");
1.165 + }
1.166 + writer.space();
1.167 + if (type != null) {
1.168 + writer.printLink(new LinkInfoImpl(LinkInfoImpl.CONTEXT_MEMBER,
1.169 + type));
1.170 + }
1.171 + writer.printTypeSummaryFooter();
1.172 + }
1.173 +
1.174 + /**
1.175 + * Print the modifier and type for the member in the member summary.
1.176 + *
1.177 + * @param member the member to print the type for.
1.178 + * @param type the type to print.
1.179 + */
1.180 + protected void printModifierAndType(ProgramElementDoc member, Type type) {
1.181 + writer.printTypeSummaryHeader();
1.182 + printModifier(member);
1.183 + if (type == null) {
1.184 + writer.space();
1.185 + if (member.isClass()) {
1.186 + print("class");
1.187 + } else {
1.188 + print("interface");
1.189 + }
1.190 + } else {
1.191 + if (member instanceof ExecutableMemberDoc &&
1.192 + ((ExecutableMemberDoc) member).typeParameters().length > 0) {
1.193 + //Code to avoid ugly wrapping in member summary table.
1.194 + writer.table(0,0,0);
1.195 + writer.trAlignVAlign("right", "");
1.196 + writer.tdNowrap();
1.197 + writer.font("-1");
1.198 + writer.code();
1.199 + int displayLength = ((AbstractExecutableMemberWriter) this).
1.200 + writeTypeParameters((ExecutableMemberDoc) member);
1.201 + if (displayLength > 10) {
1.202 + writer.br();
1.203 + }
1.204 + writer.printLink(new LinkInfoImpl(
1.205 + LinkInfoImpl.CONTEXT_SUMMARY_RETURN_TYPE, type));
1.206 + writer.codeEnd();
1.207 + writer.fontEnd();
1.208 + writer.tdEnd();
1.209 + writer.trEnd();
1.210 + writer.tableEnd();
1.211 + } else {
1.212 + writer.space();
1.213 + writer.printLink(new LinkInfoImpl(
1.214 + LinkInfoImpl.CONTEXT_SUMMARY_RETURN_TYPE, type));
1.215 + }
1.216 +
1.217 + }
1.218 + writer.printTypeSummaryFooter();
1.219 + }
1.220 +
1.221 + private void printModifier(ProgramElementDoc member) {
1.222 + if (member.isProtected()) {
1.223 + print("protected ");
1.224 + } else if (member.isPrivate()) {
1.225 + print("private ");
1.226 + } else if (!member.isPublic()) { // Package private
1.227 + writer.printText("doclet.Package_private");
1.228 + print(" ");
1.229 + }
1.230 + if (member.isMethod() && ((MethodDoc)member).isAbstract()) {
1.231 + print("abstract ");
1.232 + }
1.233 + if (member.isStatic()) {
1.234 + print("static");
1.235 + }
1.236 + }
1.237 +
1.238 + protected void printComment(ProgramElementDoc member) {
1.239 + if (member.inlineTags().length > 0) {
1.240 + writer.dd();
1.241 + writer.printInlineComment(member);
1.242 + }
1.243 + }
1.244 +
1.245 + protected String name(ProgramElementDoc member) {
1.246 + return member.name();
1.247 + }
1.248 +
1.249 + protected void printHead(MemberDoc member) {
1.250 + writer.h3();
1.251 + writer.print(member.name());
1.252 + writer.h3End();
1.253 + }
1.254 +
1.255 + protected void printFullComment(ProgramElementDoc member) {
1.256 + if(configuration().nocomment){
1.257 + return;
1.258 + }
1.259 + writer.dl();
1.260 + print(((TagletOutputImpl)
1.261 + (new DeprecatedTaglet()).getTagletOutput(member,
1.262 + writer.getTagletWriterInstance(false))).toString());
1.263 + printCommentAndTags(member);
1.264 + writer.dlEnd();
1.265 + }
1.266 +
1.267 + protected void printCommentAndTags(ProgramElementDoc member) {
1.268 + printComment(member);
1.269 + writer.printTags(member);
1.270 + }
1.271 +
1.272 + /**
1.273 + * Forward to containing writer
1.274 + */
1.275 + public void printSummaryHeader(ClassDoc cd) {
1.276 + printedSummaryHeader = true;
1.277 + writer.printSummaryHeader(this, cd);
1.278 + }
1.279 +
1.280 + /**
1.281 + * Forward to containing writer
1.282 + */
1.283 + public void printInheritedSummaryHeader(ClassDoc cd) {
1.284 + writer.printInheritedSummaryHeader(this, cd);
1.285 + }
1.286 +
1.287 + /**
1.288 + * Forward to containing writer
1.289 + */
1.290 + public void printInheritedSummaryFooter(ClassDoc cd) {
1.291 + writer.printInheritedSummaryFooter(this, cd);
1.292 + }
1.293 +
1.294 + /**
1.295 + * Forward to containing writer
1.296 + */
1.297 + public void printSummaryFooter(ClassDoc cd) {
1.298 + writer.printSummaryFooter(this, cd);
1.299 + }
1.300 +
1.301 + /**
1.302 + * Return true if the given <code>ProgramElement</code> is inherited
1.303 + * by the class that is being documented.
1.304 + *
1.305 + * @param ped The <code>ProgramElement</code> being checked.
1.306 + * return true if the <code>ProgramElement</code> is being inherited and
1.307 + * false otherwise.
1.308 + */
1.309 + protected boolean isInherited(ProgramElementDoc ped){
1.310 + if(ped.isPrivate() || (ped.isPackagePrivate() &&
1.311 + ! ped.containingPackage().equals(classdoc.containingPackage()))){
1.312 + return false;
1.313 + }
1.314 + return true;
1.315 + }
1.316 +
1.317 +
1.318 + /**
1.319 + * Generate the code for listing the deprecated APIs. Create the table
1.320 + * format for listing the API. Call methods from the sub-class to complete
1.321 + * the generation.
1.322 + */
1.323 + protected void printDeprecatedAPI(List deprmembers, String headingKey) {
1.324 + if (deprmembers.size() > 0) {
1.325 + writer.tableIndexSummary();
1.326 + writer.tableHeaderStart("#CCCCFF");
1.327 + writer.boldText(headingKey);
1.328 + writer.tableHeaderEnd();
1.329 + for (int i = 0; i < deprmembers.size(); i++) {
1.330 + ProgramElementDoc member =(ProgramElementDoc)deprmembers.get(i);
1.331 + writer.trBgcolorStyle("white", "TableRowColor");
1.332 + writer.summaryRow(0);
1.333 + writeDeprecatedLink(member);
1.334 + writer.br();
1.335 + writer.printNbsps();
1.336 + if (member.tags("deprecated").length > 0)
1.337 + writer.printInlineDeprecatedComment(member, member.tags("deprecated")[0]);
1.338 + writer.space();
1.339 + writer.summaryRowEnd();
1.340 + writer.trEnd();
1.341 + }
1.342 + writer.tableEnd();
1.343 + writer.space();
1.344 + writer.p();
1.345 + }
1.346 + }
1.347 +
1.348 + /**
1.349 + * Print use info.
1.350 + */
1.351 + protected void printUseInfo(Object mems, String heading) {
1.352 + if (mems == null) {
1.353 + return;
1.354 + }
1.355 + List members = (List)mems;
1.356 + if (members.size() > 0) {
1.357 + writer.tableIndexSummary();
1.358 + writer.tableUseInfoHeaderStart("#CCCCFF");
1.359 + writer.print(heading);
1.360 + writer.tableHeaderEnd();
1.361 + for (Iterator it = members.iterator(); it.hasNext(); ) {
1.362 + ProgramElementDoc pgmdoc = (ProgramElementDoc)it.next();
1.363 + ClassDoc cd = pgmdoc.containingClass();
1.364 +
1.365 + writer.printSummaryLinkType(this, pgmdoc);
1.366 + if (cd != null && !(pgmdoc instanceof ConstructorDoc)
1.367 + && !(pgmdoc instanceof ClassDoc)) {
1.368 + // Add class context
1.369 + writer.bold(cd.name() + ".");
1.370 + }
1.371 + writeSummaryLink(
1.372 + pgmdoc instanceof ClassDoc ?
1.373 + LinkInfoImpl.CONTEXT_CLASS_USE : LinkInfoImpl.CONTEXT_MEMBER,
1.374 + cd, pgmdoc);
1.375 + writer.printSummaryLinkComment(this, pgmdoc);
1.376 + }
1.377 + writer.tableEnd();
1.378 + writer.space();
1.379 + writer.p();
1.380 + }
1.381 + }
1.382 +
1.383 + protected void navDetailLink(List members) {
1.384 + printNavDetailLink(members.size() > 0? true: false);
1.385 + }
1.386 +
1.387 +
1.388 + protected void navSummaryLink(List members,
1.389 + VisibleMemberMap visibleMemberMap) {
1.390 + if (members.size() > 0) {
1.391 + printNavSummaryLink(null, true);
1.392 + return;
1.393 + } else {
1.394 + ClassDoc icd = classdoc.superclass();
1.395 + while (icd != null) {
1.396 + List inhmembers = visibleMemberMap.getMembersFor(icd);
1.397 + if (inhmembers.size() > 0) {
1.398 + printNavSummaryLink(icd, true);
1.399 + return;
1.400 + }
1.401 + icd = icd.superclass();
1.402 + }
1.403 + }
1.404 + printNavSummaryLink(null, false);
1.405 + }
1.406 +
1.407 + protected void serialWarning(SourcePosition pos, String key, String a1, String a2) {
1.408 + if (configuration().serialwarn) {
1.409 + ConfigurationImpl.getInstance().getDocletSpecificMsg().warning(pos, key, a1, a2);
1.410 + }
1.411 + }
1.412 +
1.413 + public ProgramElementDoc[] eligibleMembers(ProgramElementDoc[] members) {
1.414 + return nodepr? Util.excludeDeprecatedMembers(members): members;
1.415 + }
1.416 +
1.417 + public ConfigurationImpl configuration() {
1.418 + return writer.configuration;
1.419 + }
1.420 +
1.421 + /**
1.422 + * {@inheritDoc}
1.423 + */
1.424 + public void writeMemberSummary(ClassDoc classDoc, ProgramElementDoc member,
1.425 + Tag[] firstSentenceTags, boolean isFirst, boolean isLast) {
1.426 + writer.printSummaryLinkType(this, member);
1.427 + writeSummaryLink(classDoc, member);
1.428 + writer.printSummaryLinkComment(this, member, firstSentenceTags);
1.429 + }
1.430 +}
