Mon, 09 Mar 2009 23:53:41 -0700
Merge
1 /*
2 * Copyright 1997-2008 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
26 package com.sun.tools.doclets.formats.html;
28 import java.lang.reflect.Modifier;
29 import java.util.*;
31 import com.sun.javadoc.*;
32 import com.sun.tools.doclets.internal.toolkit.util.*;
33 import com.sun.tools.doclets.internal.toolkit.taglets.*;
35 /**
36 * The base class for member writers.
37 *
38 * @author Robert Field
39 * @author Atul M Dambalkar
40 * @author Jamie Ho (Re-write)
41 * @author Bhavesh Patel (Modified)
42 */
43 public abstract class AbstractMemberWriter {
45 protected boolean printedSummaryHeader = false;
46 protected final SubWriterHolderWriter writer;
47 protected final ClassDoc classdoc;
48 public final boolean nodepr;
50 public AbstractMemberWriter(SubWriterHolderWriter writer,
51 ClassDoc classdoc) {
52 this.writer = writer;
53 this.nodepr = configuration().nodeprecated;
54 this.classdoc = classdoc;
55 }
57 public AbstractMemberWriter(SubWriterHolderWriter writer) {
58 this(writer, null);
59 }
61 /*** abstracts ***/
63 public abstract void printSummaryLabel(ClassDoc cd);
65 public abstract void printInheritedSummaryLabel(ClassDoc cd);
67 public abstract void printSummaryAnchor(ClassDoc cd);
69 public abstract void printInheritedSummaryAnchor(ClassDoc cd);
71 protected abstract void printSummaryType(ProgramElementDoc member);
73 protected void writeSummaryLink(ClassDoc cd, ProgramElementDoc member) {
74 writeSummaryLink(LinkInfoImpl.CONTEXT_MEMBER, cd, member);
75 }
77 protected abstract void writeSummaryLink(int context,
78 ClassDoc cd,
79 ProgramElementDoc member);
81 protected abstract void writeInheritedSummaryLink(ClassDoc cd,
82 ProgramElementDoc member);
84 protected abstract void writeDeprecatedLink(ProgramElementDoc member);
86 protected abstract void printNavSummaryLink(ClassDoc cd, boolean link);
88 protected abstract void printNavDetailLink(boolean link);
90 /*** ***/
92 protected void print(String str) {
93 writer.print(str);
94 writer.displayLength += str.length();
95 }
97 protected void print(char ch) {
98 writer.print(ch);
99 writer.displayLength++;
100 }
102 protected void strong(String str) {
103 writer.strong(str);
104 writer.displayLength += str.length();
105 }
107 /**
108 * Return a string describing the access modifier flags.
109 * Don't include native or synchronized.
110 *
111 * The modifier names are returned in canonical order, as
112 * specified by <em>The Java Language Specification</em>.
113 */
114 protected String modifierString(MemberDoc member) {
115 int ms = member.modifierSpecifier();
116 int no = Modifier.NATIVE | Modifier.SYNCHRONIZED;
117 return Modifier.toString(ms & ~no);
118 }
120 protected String typeString(MemberDoc member) {
121 String type = "";
122 if (member instanceof MethodDoc) {
123 type = ((MethodDoc)member).returnType().toString();
124 } else if (member instanceof FieldDoc) {
125 type = ((FieldDoc)member).type().toString();
126 }
127 return type;
128 }
130 protected void printModifiers(MemberDoc member) {
131 String mod = modifierString(member);
132 // According to JLS, we should not be showing public modifier for
133 // interface methods.
134 if ((member.isField() || member.isMethod()) &&
135 writer instanceof ClassWriterImpl &&
136 ((ClassWriterImpl) writer).getClassDoc().isInterface()) {
137 mod = Util.replaceText(mod, "public", "").trim();
138 }
139 if(mod.length() > 0) {
140 print(mod);
141 print(' ');
142 }
143 }
145 protected String makeSpace(int len) {
146 if (len <= 0) {
147 return "";
148 }
149 StringBuffer sb = new StringBuffer(len);
150 for(int i = 0; i < len; i++) {
151 sb.append(' ');
152 }
153 return sb.toString();
154 }
156 /**
157 * Print 'static' if static and type link.
158 */
159 protected void printStaticAndType(boolean isStatic, Type type) {
160 writer.printTypeSummaryHeader();
161 if (isStatic) {
162 print("static");
163 }
164 writer.space();
165 if (type != null) {
166 writer.printLink(new LinkInfoImpl(LinkInfoImpl.CONTEXT_MEMBER,
167 type));
168 }
169 writer.printTypeSummaryFooter();
170 }
172 /**
173 * Print the modifier and type for the member in the member summary.
174 *
175 * @param member the member to print the type for.
176 * @param type the type to print.
177 */
178 protected void printModifierAndType(ProgramElementDoc member, Type type) {
179 writer.printTypeSummaryHeader();
180 printModifier(member);
181 if (type == null) {
182 writer.space();
183 if (member.isClass()) {
184 print("class");
185 } else {
186 print("interface");
187 }
188 } else {
189 if (member instanceof ExecutableMemberDoc &&
190 ((ExecutableMemberDoc) member).typeParameters().length > 0) {
191 //Code to avoid ugly wrapping in member summary table.
192 writer.table(0,0,0);
193 writer.trAlignVAlign("right", "");
194 writer.tdNowrap();
195 writer.font("-1");
196 writer.code();
197 int displayLength = ((AbstractExecutableMemberWriter) this).
198 writeTypeParameters((ExecutableMemberDoc) member);
199 if (displayLength > 10) {
200 writer.br();
201 }
202 writer.printLink(new LinkInfoImpl(
203 LinkInfoImpl.CONTEXT_SUMMARY_RETURN_TYPE, type));
204 writer.codeEnd();
205 writer.fontEnd();
206 writer.tdEnd();
207 writer.trEnd();
208 writer.tableEnd();
209 } else {
210 writer.space();
211 writer.printLink(new LinkInfoImpl(
212 LinkInfoImpl.CONTEXT_SUMMARY_RETURN_TYPE, type));
213 }
215 }
216 writer.printTypeSummaryFooter();
217 }
219 private void printModifier(ProgramElementDoc member) {
220 if (member.isProtected()) {
221 print("protected ");
222 } else if (member.isPrivate()) {
223 print("private ");
224 } else if (!member.isPublic()) { // Package private
225 writer.printText("doclet.Package_private");
226 print(" ");
227 }
228 if (member.isMethod() && ((MethodDoc)member).isAbstract()) {
229 print("abstract ");
230 }
231 if (member.isStatic()) {
232 print("static");
233 }
234 }
236 /**
237 * Print the deprecated output for the given member.
238 *
239 * @param member the member being documented.
240 */
241 protected void printDeprecated(ProgramElementDoc member) {
242 String output = (new DeprecatedTaglet()).getTagletOutput(member,
243 writer.getTagletWriterInstance(false)).toString().trim();
244 if (!output.isEmpty()) {
245 writer.printMemberDetailsListStartTag();
246 writer.print(output);
247 }
248 }
250 protected void printComment(ProgramElementDoc member) {
251 if (member.inlineTags().length > 0) {
252 writer.printMemberDetailsListStartTag();
253 writer.dd();
254 writer.printInlineComment(member);
255 writer.ddEnd();
256 }
257 }
259 protected String name(ProgramElementDoc member) {
260 return member.name();
261 }
263 protected void printHead(MemberDoc member) {
264 writer.h3();
265 writer.print(member.name());
266 writer.h3End();
267 }
269 protected void printFullComment(ProgramElementDoc member) {
270 if(configuration().nocomment){
271 return;
272 }
273 writer.dl();
274 print(((TagletOutputImpl)
275 (new DeprecatedTaglet()).getTagletOutput(member,
276 writer.getTagletWriterInstance(false))).toString());
277 printCommentAndTags(member);
278 writer.dlEnd();
279 }
281 protected void printCommentAndTags(ProgramElementDoc member) {
282 printComment(member);
283 writer.printTags(member);
284 }
286 /**
287 * Write the member footer.
288 */
289 protected void printMemberFooter() {
290 writer.printMemberDetailsListEndTag();
291 assert !writer.getMemberDetailsListPrinted();
292 }
294 /**
295 * Forward to containing writer
296 */
297 public void printSummaryHeader(ClassDoc cd) {
298 printedSummaryHeader = true;
299 writer.printSummaryHeader(this, cd);
300 }
302 /**
303 * Forward to containing writer
304 */
305 public void printInheritedSummaryHeader(ClassDoc cd) {
306 writer.printInheritedSummaryHeader(this, cd);
307 }
309 /**
310 * Forward to containing writer
311 */
312 public void printInheritedSummaryFooter(ClassDoc cd) {
313 writer.printInheritedSummaryFooter(this, cd);
314 }
316 /**
317 * Forward to containing writer
318 */
319 public void printSummaryFooter(ClassDoc cd) {
320 writer.printSummaryFooter(this, cd);
321 }
323 /**
324 * Return true if the given <code>ProgramElement</code> is inherited
325 * by the class that is being documented.
326 *
327 * @param ped The <code>ProgramElement</code> being checked.
328 * return true if the <code>ProgramElement</code> is being inherited and
329 * false otherwise.
330 */
331 protected boolean isInherited(ProgramElementDoc ped){
332 if(ped.isPrivate() || (ped.isPackagePrivate() &&
333 ! ped.containingPackage().equals(classdoc.containingPackage()))){
334 return false;
335 }
336 return true;
337 }
340 /**
341 * Generate the code for listing the deprecated APIs. Create the table
342 * format for listing the API. Call methods from the sub-class to complete
343 * the generation.
344 */
345 protected void printDeprecatedAPI(List<Doc> deprmembers, String headingKey) {
346 if (deprmembers.size() > 0) {
347 writer.tableIndexSummary();
348 writer.tableHeaderStart("#CCCCFF");
349 writer.strongText(headingKey);
350 writer.tableHeaderEnd();
351 for (int i = 0; i < deprmembers.size(); i++) {
352 ProgramElementDoc member =(ProgramElementDoc)deprmembers.get(i);
353 writer.trBgcolorStyle("white", "TableRowColor");
354 writer.summaryRow(0);
355 writeDeprecatedLink(member);
356 writer.br();
357 writer.printNbsps();
358 if (member.tags("deprecated").length > 0)
359 writer.printInlineDeprecatedComment(member, member.tags("deprecated")[0]);
360 writer.space();
361 writer.summaryRowEnd();
362 writer.trEnd();
363 }
364 writer.tableEnd();
365 writer.space();
366 writer.p();
367 }
368 }
370 /**
371 * Print use info.
372 */
373 protected void printUseInfo(List<? extends ProgramElementDoc> mems, String heading) {
374 if (mems == null) {
375 return;
376 }
377 List<? extends ProgramElementDoc> members = mems;
378 if (members.size() > 0) {
379 writer.tableIndexSummary();
380 writer.tableUseInfoHeaderStart("#CCCCFF");
381 writer.print(heading);
382 writer.tableHeaderEnd();
383 for (Iterator<? extends ProgramElementDoc> it = members.iterator(); it.hasNext(); ) {
384 ProgramElementDoc pgmdoc = it.next();
385 ClassDoc cd = pgmdoc.containingClass();
387 writer.printSummaryLinkType(this, pgmdoc);
388 if (cd != null && !(pgmdoc instanceof ConstructorDoc)
389 && !(pgmdoc instanceof ClassDoc)) {
390 // Add class context
391 writer.strong(cd.name() + ".");
392 }
393 writeSummaryLink(
394 pgmdoc instanceof ClassDoc ?
395 LinkInfoImpl.CONTEXT_CLASS_USE : LinkInfoImpl.CONTEXT_MEMBER,
396 cd, pgmdoc);
397 writer.printSummaryLinkComment(this, pgmdoc);
398 }
399 writer.tableEnd();
400 writer.space();
401 writer.p();
402 }
403 }
405 protected void navDetailLink(List<?> members) {
406 printNavDetailLink(members.size() > 0? true: false);
407 }
410 protected void navSummaryLink(List<?> members,
411 VisibleMemberMap visibleMemberMap) {
412 if (members.size() > 0) {
413 printNavSummaryLink(null, true);
414 return;
415 } else {
416 ClassDoc icd = classdoc.superclass();
417 while (icd != null) {
418 List<?> inhmembers = visibleMemberMap.getMembersFor(icd);
419 if (inhmembers.size() > 0) {
420 printNavSummaryLink(icd, true);
421 return;
422 }
423 icd = icd.superclass();
424 }
425 }
426 printNavSummaryLink(null, false);
427 }
429 protected void serialWarning(SourcePosition pos, String key, String a1, String a2) {
430 if (configuration().serialwarn) {
431 ConfigurationImpl.getInstance().getDocletSpecificMsg().warning(pos, key, a1, a2);
432 }
433 }
435 public ProgramElementDoc[] eligibleMembers(ProgramElementDoc[] members) {
436 return nodepr? Util.excludeDeprecatedMembers(members): members;
437 }
439 public ConfigurationImpl configuration() {
440 return writer.configuration;
441 }
443 /**
444 * {@inheritDoc}
445 */
446 public void writeMemberSummary(ClassDoc classDoc, ProgramElementDoc member,
447 Tag[] firstSentenceTags, boolean isFirst, boolean isLast) {
448 writer.printSummaryLinkType(this, member);
449 writeSummaryLink(classDoc, member);
450 writer.printSummaryLinkComment(this, member, firstSentenceTags);
451 }
452 }