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