View Javadoc
1   /*
2    * Copyright (c) 1997, 2013, Oracle and/or its affiliates. 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.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package com.sun.tools.doclets.formats.html;
27  
28  import java.io.*;
29  import java.util.*;
30  
31  import com.sun.javadoc.*;
32  import com.sun.tools.doclets.formats.html.markup.*;
33  import com.sun.tools.doclets.internal.toolkit.*;
34  import com.sun.tools.doclets.internal.toolkit.util.*;
35  
36  /**
37   * This abstract class exists to provide functionality needed in the
38   * the formatting of member information.  Since AbstractSubWriter and its
39   * subclasses control this, they would be the logical place to put this.
40   * However, because each member type has its own subclass, subclassing
41   * can not be used effectively to change formatting.  The concrete
42   * class subclass of this class can be subclassed to change formatting.
43   *
44   *  <p><b>This is NOT part of any supported API.
45   *  If you write code that depends on this, you do so at your own risk.
46   *  This code and its internal interfaces are subject to change or
47   *  deletion without notice.</b>
48   *
49   * @see AbstractMemberWriter
50   * @see ClassWriterImpl
51   *
52   * @author Robert Field
53   * @author Atul M Dambalkar
54   * @author Bhavesh Patel (Modified)
55   */
56  public abstract class SubWriterHolderWriter extends HtmlDocletWriter {
57  
58      public SubWriterHolderWriter(ConfigurationImpl configuration, DocPath filename)
59              throws IOException {
60          super(configuration, filename);
61      }
62  
63      /**
64       * Add the summary header.
65       *
66       * @param mw the writer for the member being documented
67       * @param cd the classdoc to be documented
68       * @param memberTree the content tree to which the summary header will be added
69       */
70      public void addSummaryHeader(AbstractMemberWriter mw, ClassDoc cd,
71              Content memberTree) {
72          mw.addSummaryAnchor(cd, memberTree);
73          mw.addSummaryLabel(memberTree);
74      }
75  
76      /**
77       * Get the summary table.
78       *
79       * @param mw the writer for the member being documented
80       * @param cd the classdoc to be documented
81       * @param tableContents list of summary table contents
82       * @param showTabs true if the table needs to show tabs
83       * @return the content tree for the summary table
84       */
85      public Content getSummaryTableTree(AbstractMemberWriter mw, ClassDoc cd,
86              List<Content> tableContents, boolean showTabs) {
87          Content caption;
88          if (showTabs) {
89              caption = getTableCaption(mw.methodTypes);
90              generateMethodTypesScript(mw.typeMap, mw.methodTypes);
91          }
92          else {
93              caption = getTableCaption(mw.getCaption());
94          }
95          Content table = HtmlTree.TABLE(HtmlStyle.memberSummary, 0, 3, 0,
96                  mw.getTableSummary(), caption);
97          table.addContent(getSummaryTableHeader(mw.getSummaryTableHeader(cd), "col"));
98          for (int i = 0; i < tableContents.size(); i++) {
99              table.addContent(tableContents.get(i));
100         }
101         return table;
102     }
103 
104     /**
105      * Get the summary table caption.
106      *
107      * @param methodTypes set comprising of method types to show as table caption
108      * @return the caption for the summary table
109      */
110     public Content getTableCaption(Set<MethodTypes> methodTypes) {
111         Content tabbedCaption = new HtmlTree(HtmlTag.CAPTION);
112         for (MethodTypes type : methodTypes) {
113             Content captionSpan;
114             Content span;
115             if (type.isDefaultTab()) {
116                 captionSpan = HtmlTree.SPAN(new StringContent(type.text()));
117                 span = HtmlTree.SPAN(type.tabId(),
118                         HtmlStyle.activeTableTab, captionSpan);
119             } else {
120                 captionSpan = HtmlTree.SPAN(getMethodTypeLinks(type));
121                 span = HtmlTree.SPAN(type.tabId(),
122                         HtmlStyle.tableTab, captionSpan);
123             }
124             Content tabSpan = HtmlTree.SPAN(HtmlStyle.tabEnd, getSpace());
125             span.addContent(tabSpan);
126             tabbedCaption.addContent(span);
127         }
128         return tabbedCaption;
129     }
130 
131     /**
132      * Get the method type links for the table caption.
133      *
134      * @param methodType the method type to be displayed as link
135      * @return the content tree for the method type link
136      */
137     public Content getMethodTypeLinks(MethodTypes methodType) {
138         String jsShow = "javascript:show(" + methodType.value() +");";
139         HtmlTree link = HtmlTree.A(jsShow, new StringContent(methodType.text()));
140         return link;
141     }
142 
143     /**
144      * Add the inherited summary header.
145      *
146      * @param mw the writer for the member being documented
147      * @param cd the classdoc to be documented
148      * @param inheritedTree the content tree to which the inherited summary header will be added
149      */
150     public void addInheritedSummaryHeader(AbstractMemberWriter mw, ClassDoc cd,
151             Content inheritedTree) {
152         mw.addInheritedSummaryAnchor(cd, inheritedTree);
153         mw.addInheritedSummaryLabel(cd, inheritedTree);
154     }
155 
156     /**
157      * Add the index comment.
158      *
159      * @param member the member being documented
160      * @param contentTree the content tree to which the comment will be added
161      */
162     protected void addIndexComment(Doc member, Content contentTree) {
163         addIndexComment(member, member.firstSentenceTags(), contentTree);
164     }
165 
166     /**
167      * Add the index comment.
168      *
169      * @param member the member being documented
170      * @param firstSentenceTags the first sentence tags for the member to be documented
171      * @param tdSummary the content tree to which the comment will be added
172      */
173     protected void addIndexComment(Doc member, Tag[] firstSentenceTags,
174             Content tdSummary) {
175         Tag[] deprs = member.tags("deprecated");
176         Content div;
177         if (Util.isDeprecated((ProgramElementDoc) member)) {
178             Content deprLabel = HtmlTree.SPAN(HtmlStyle.deprecatedLabel, deprecatedPhrase);
179             div = HtmlTree.DIV(HtmlStyle.block, deprLabel);
180             div.addContent(getSpace());
181             if (deprs.length > 0) {
182                 addInlineDeprecatedComment(member, deprs[0], div);
183             }
184             tdSummary.addContent(div);
185             return;
186         } else {
187             ClassDoc cd = ((ProgramElementDoc)member).containingClass();
188             if (cd != null && Util.isDeprecated(cd)) {
189                 Content deprLabel = HtmlTree.SPAN(HtmlStyle.deprecatedLabel, deprecatedPhrase);
190                 div = HtmlTree.DIV(HtmlStyle.block, deprLabel);
191                 div.addContent(getSpace());
192                 tdSummary.addContent(div);
193             }
194         }
195         addSummaryComment(member, firstSentenceTags, tdSummary);
196     }
197 
198     /**
199      * Add the summary type for the member.
200      *
201      * @param mw the writer for the member being documented
202      * @param member the member to be documented
203      * @param tdSummaryType the content tree to which the type will be added
204      */
205     public void addSummaryType(AbstractMemberWriter mw, ProgramElementDoc member,
206             Content tdSummaryType) {
207         mw.addSummaryType(member, tdSummaryType);
208     }
209 
210     /**
211      * Add the summary link for the member.
212      *
213      * @param mw the writer for the member being documented
214      * @param member the member to be documented
215      * @param contentTree the content tree to which the link will be added
216      */
217     public void addSummaryLinkComment(AbstractMemberWriter mw,
218             ProgramElementDoc member, Content contentTree) {
219         addSummaryLinkComment(mw, member, member.firstSentenceTags(), contentTree);
220     }
221 
222     /**
223      * Add the summary link comment.
224      *
225      * @param mw the writer for the member being documented
226      * @param member the member being documented
227      * @param firstSentenceTags the first sentence tags for the member to be documented
228      * @param tdSummary the content tree to which the comment will be added
229      */
230     public void addSummaryLinkComment(AbstractMemberWriter mw,
231             ProgramElementDoc member, Tag[] firstSentenceTags, Content tdSummary) {
232         addIndexComment(member, firstSentenceTags, tdSummary);
233     }
234 
235     /**
236      * Add the inherited member summary.
237      *
238      * @param mw the writer for the member being documented
239      * @param cd the class being documented
240      * @param member the member being documented
241      * @param isFirst true if its the first link being documented
242      * @param linksTree the content tree to which the summary will be added
243      */
244     public void addInheritedMemberSummary(AbstractMemberWriter mw, ClassDoc cd,
245             ProgramElementDoc member, boolean isFirst, Content linksTree) {
246         if (! isFirst) {
247             linksTree.addContent(", ");
248         }
249         mw.addInheritedSummaryLink(cd, member, linksTree);
250     }
251 
252     /**
253      * Get the document content header tree
254      *
255      * @return a content tree the document content header
256      */
257     public Content getContentHeader() {
258         HtmlTree div = new HtmlTree(HtmlTag.DIV);
259         div.addStyle(HtmlStyle.contentContainer);
260         return div;
261     }
262 
263     /**
264      * Get the member header tree
265      *
266      * @return a content tree the member header
267      */
268     public Content getMemberTreeHeader() {
269         HtmlTree li = new HtmlTree(HtmlTag.LI);
270         li.addStyle(HtmlStyle.blockList);
271         return li;
272     }
273 
274     /**
275      * Get the member tree
276      *
277      * @param contentTree the tree used to generate the complete member tree
278      * @return a content tree for the member
279      */
280     public Content getMemberTree(Content contentTree) {
281         Content ul = HtmlTree.UL(HtmlStyle.blockList, contentTree);
282         return ul;
283     }
284 
285     /**
286      * Get the member summary tree
287      *
288      * @param contentTree the tree used to generate the member summary tree
289      * @return a content tree for the member summary
290      */
291     public Content getMemberSummaryTree(Content contentTree) {
292         return getMemberTree(HtmlStyle.summary, contentTree);
293     }
294 
295     /**
296      * Get the member details tree
297      *
298      * @param contentTree the tree used to generate the member details tree
299      * @return a content tree for the member details
300      */
301     public Content getMemberDetailsTree(Content contentTree) {
302         return getMemberTree(HtmlStyle.details, contentTree);
303     }
304 
305     /**
306      * Get the member tree
307      *
308      * @param style the style class to be added to the content tree
309      * @param contentTree the tree used to generate the complete member tree
310      */
311     public Content getMemberTree(HtmlStyle style, Content contentTree) {
312         Content div = HtmlTree.DIV(style, getMemberTree(contentTree));
313         return div;
314     }
315 }