1 /*
2 * Copyright (c) 2013, 2019, 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.toolkit.builders;
27
28 import javax.lang.model.element.ModuleElement;
29
30 import jdk.javadoc.internal.doclets.toolkit.Content;
31 import jdk.javadoc.internal.doclets.toolkit.DocFilesHandler;
32 import jdk.javadoc.internal.doclets.toolkit.DocletException;
33 import jdk.javadoc.internal.doclets.toolkit.ModuleSummaryWriter;
34
35
36 /**
37 * Builds the summary for a given module.
38 *
39 * <p><b>This is NOT part of any supported API.
40 * If you write code that depends on this, you do so at your own risk.
41 * This code and its internal interfaces are subject to change or
42 * deletion without notice.</b>
43 */
44 public class ModuleSummaryBuilder extends AbstractBuilder {
45
46 /**
47 * The module being documented.
48 */
49 private final ModuleElement mdle;
50
51 /**
52 * The doclet specific writer that will output the result.
53 */
54 private final ModuleSummaryWriter moduleWriter;
55
56 /**
57 * Construct a new ModuleSummaryBuilder.
58 *
59 * @param context the build context.
60 * @param mdle the module being documented.
61 * @param moduleWriter the doclet specific writer that will output the
62 * result.
63 */
64 private ModuleSummaryBuilder(Context context,
65 ModuleElement mdle, ModuleSummaryWriter moduleWriter) {
66 super(context);
67 this.mdle = mdle;
68 this.moduleWriter = moduleWriter;
69 }
70
71 /**
72 * Construct a new ModuleSummaryBuilder.
73 *
74 * @param context the build context.
75 * @param mdle the module being documented.
76 * @param moduleWriter the doclet specific writer that will output the
77 * result.
78 *
79 * @return an instance of a ModuleSummaryBuilder.
80 */
81 public static ModuleSummaryBuilder getInstance(Context context,
82 ModuleElement mdle, ModuleSummaryWriter moduleWriter) {
83 return new ModuleSummaryBuilder(context, mdle, moduleWriter);
84 }
85
86 /**
87 * Build the module summary.
88 *
89 * @throws DocletException if there is a problem while building the documentation
90 */
91 @Override
92 public void build() throws DocletException {
93 if (moduleWriter == null) {
94 //Doclet does not support this output.
95 return;
96 }
97 buildModuleDoc();
98 }
99
100 /**
101 * Build the module documentation.
102 *
103 * @throws DocletException if there is a problem while building the documentation
104 */
105 protected void buildModuleDoc() throws DocletException {
106 Content contentTree = moduleWriter.getModuleHeader(mdle.getQualifiedName().toString());
107
108 buildContent();
109
110 moduleWriter.addModuleFooter();
111 moduleWriter.printDocument(contentTree);
112 DocFilesHandler docFilesHandler = configuration.getWriterFactory().getDocFilesHandler(mdle);
113 docFilesHandler.copyDocFiles();
114 }
115
116 /**
117 * Build the content for the module doc.
118 *
119 * @throws DocletException if there is a problem while building the documentation
120 */
121 protected void buildContent() throws DocletException {
122 Content moduleContentTree = moduleWriter.getContentHeader();
123
124 buildModuleDescription(moduleContentTree);
125 buildModuleTags(moduleContentTree);
126 buildSummary(moduleContentTree);
127
128 moduleWriter.addModuleContent(moduleContentTree);
129 }
130
131 /**
132 * Build the module summary.
133 *
134 * @param moduleContentTree the module content tree to which the summaries will
135 * be added
136 * @throws DocletException if there is a problem while building the documentation
137 */
138 protected void buildSummary(Content moduleContentTree) throws DocletException {
139 Content summaryContentTree = moduleWriter.getSummaryHeader();
140
141 buildPackagesSummary(summaryContentTree);
142 buildModulesSummary(summaryContentTree);
143 buildServicesSummary(summaryContentTree);
144
145 moduleContentTree.add(moduleWriter.getSummaryTree(summaryContentTree));
146 }
147
148 /**
149 * Build the modules summary.
150 *
151 * @param summaryContentTree the content tree to which the summaries will
152 * be added
153 */
154 protected void buildModulesSummary(Content summaryContentTree) {
155 moduleWriter.addModulesSummary(summaryContentTree);
156 }
157
158 /**
159 * Build the package summary.
160 *
161 * @param summaryContentTree the content tree to which the summaries will be added
162 */
163 protected void buildPackagesSummary(Content summaryContentTree) {
164 moduleWriter.addPackagesSummary(summaryContentTree);
165 }
166
167 /**
168 * Build the services summary.
169 *
170 * @param summaryContentTree the content tree to which the summaries will be added
171 */
172 protected void buildServicesSummary(Content summaryContentTree) {
173 moduleWriter.addServicesSummary(summaryContentTree);
174 }
175
176 /**
177 * Build the description for the module.
178 *
179 * @param moduleContentTree the tree to which the module description will
180 * be added
181 */
182 protected void buildModuleDescription(Content moduleContentTree) {
183 if (!configuration.nocomment) {
184 moduleWriter.addModuleDescription(moduleContentTree);
185 }
186 }
187
188 /**
189 * Build the tags of the summary.
190 *
191 * @param moduleContentTree the tree to which the module tags will be added
192 */
193 protected void buildModuleTags(Content moduleContentTree) {
194 if (!configuration.nocomment) {
195 moduleWriter.addModuleTags(moduleContentTree);
196 }
197 }
198 }