Tue, 09 Apr 2013 14:18:22 -0700
8005091: javadoc should be able to return the receiver type
Reviewed-by: jjg
1 /*
2 * Copyright (c) 1998, 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 */
26 package com.sun.tools.doclets.formats.html;
28 import java.io.*;
29 import java.util.*;
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.DocPath;
36 /**
37 * Abstract class to generate the overview files in
38 * Frame and Non-Frame format. This will be sub-classed by to
39 * generate overview-frame.html as well as overview-summary.html.
40 *
41 * <p><b>This is NOT part of any supported API.
42 * If you write code that depends on this, you do so at your own risk.
43 * This code and its internal interfaces are subject to change or
44 * deletion without notice.</b>
45 *
46 * @author Atul M Dambalkar
47 * @author Bhavesh Patel (Modified)
48 */
49 public abstract class AbstractPackageIndexWriter extends HtmlDocletWriter {
51 /**
52 * Array of Packages to be documented.
53 */
54 protected PackageDoc[] packages;
56 /**
57 * Constructor. Also initializes the packages variable.
58 *
59 * @param configuration The current configuration
60 * @param filename Name of the package index file to be generated.
61 */
62 public AbstractPackageIndexWriter(ConfigurationImpl configuration,
63 DocPath filename) throws IOException {
64 super(configuration, filename);
65 packages = configuration.packages;
66 }
68 /**
69 * Adds the navigation bar header to the documentation tree.
70 *
71 * @param body the document tree to which the navigation bar header will be added
72 */
73 protected abstract void addNavigationBarHeader(Content body);
75 /**
76 * Adds the navigation bar footer to the documentation tree.
77 *
78 * @param body the document tree to which the navigation bar footer will be added
79 */
80 protected abstract void addNavigationBarFooter(Content body);
82 /**
83 * Adds the overview header to the documentation tree.
84 *
85 * @param body the document tree to which the overview header will be added
86 */
87 protected abstract void addOverviewHeader(Content body);
89 /**
90 * Adds the packages list to the documentation tree.
91 *
92 * @param packages an array of packagedoc objects
93 * @param text caption for the table
94 * @param tableSummary summary for the table
95 * @param body the document tree to which the packages list will be added
96 */
97 protected abstract void addPackagesList(PackageDoc[] packages, String text,
98 String tableSummary, Content body);
100 /**
101 * Generate and prints the contents in the package index file. Call appropriate
102 * methods from the sub-class in order to generate Frame or Non
103 * Frame format.
104 *
105 * @param title the title of the window.
106 * @param includeScript boolean set true if windowtitle script is to be included
107 */
108 protected void buildPackageIndexFile(String title, boolean includeScript) throws IOException {
109 String windowOverview = configuration.getText(title);
110 Content body = getBody(includeScript, getWindowTitle(windowOverview));
111 addNavigationBarHeader(body);
112 addOverviewHeader(body);
113 addIndex(body);
114 addOverview(body);
115 addNavigationBarFooter(body);
116 printHtmlDocument(configuration.metakeywords.getOverviewMetaKeywords(title,
117 configuration.doctitle), includeScript, body);
118 }
120 /**
121 * Default to no overview, override to add overview.
122 *
123 * @param body the document tree to which the overview will be added
124 */
125 protected void addOverview(Content body) throws IOException {
126 }
128 /**
129 * Adds the frame or non-frame package index to the documentation tree.
130 *
131 * @param body the document tree to which the index will be added
132 */
133 protected void addIndex(Content body) {
134 addIndexContents(packages, "doclet.Package_Summary",
135 configuration.getText("doclet.Member_Table_Summary",
136 configuration.getText("doclet.Package_Summary"),
137 configuration.getText("doclet.packages")), body);
138 }
140 /**
141 * Adds package index contents. Call appropriate methods from
142 * the sub-classes. Adds it to the body HtmlTree
143 *
144 * @param packages array of packages to be documented
145 * @param text string which will be used as the heading
146 * @param tableSummary summary for the table
147 * @param body the document tree to which the index contents will be added
148 */
149 protected void addIndexContents(PackageDoc[] packages, String text,
150 String tableSummary, Content body) {
151 if (packages.length > 0) {
152 Arrays.sort(packages);
153 HtmlTree div = new HtmlTree(HtmlTag.DIV);
154 div.addStyle(HtmlStyle.indexHeader);
155 addAllClassesLink(div);
156 if (configuration.showProfiles) {
157 addAllProfilesLink(div);
158 }
159 body.addContent(div);
160 if (configuration.showProfiles) {
161 String profileSummary = configuration.getText("doclet.Profiles");
162 String profilesTableSummary = configuration.getText("doclet.Member_Table_Summary",
163 configuration.getText("doclet.Profile_Summary"),
164 configuration.getText("doclet.profiles"));
165 addProfilesList(profileSummary, profilesTableSummary, body);
166 }
167 addPackagesList(packages, text, tableSummary, body);
168 }
169 }
171 /**
172 * Adds the doctitle to the documentation tree, if it is specified on the command line.
173 *
174 * @param body the document tree to which the title will be added
175 */
176 protected void addConfigurationTitle(Content body) {
177 if (configuration.doctitle.length() > 0) {
178 Content title = new RawHtml(configuration.doctitle);
179 Content heading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING,
180 HtmlStyle.title, title);
181 Content div = HtmlTree.DIV(HtmlStyle.header, heading);
182 body.addContent(div);
183 }
184 }
186 /**
187 * Returns highlighted "Overview", in the navigation bar as this is the
188 * overview page.
189 *
190 * @return a Content object to be added to the documentation tree
191 */
192 protected Content getNavLinkContents() {
193 Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, overviewLabel);
194 return li;
195 }
197 /**
198 * Do nothing. This will be overridden.
199 *
200 * @param div the document tree to which the all classes link will be added
201 */
202 protected void addAllClassesLink(Content div) {
203 }
205 /**
206 * Do nothing. This will be overridden.
207 *
208 * @param div the document tree to which the all profiles link will be added
209 */
210 protected void addAllProfilesLink(Content div) {
211 }
213 /**
214 * Do nothing. This will be overridden.
215 *
216 * @param profileSummary the profile summary heading
217 * @param profilesTableSummary the profiles table summary information
218 * @param body the content tree to which the profiles list will be added
219 */
220 protected void addProfilesList(String profileSummary, String profilesTableSummary,
221 Content body) {
222 }
223 }