1 /*
2 * Copyright (c) 2003, 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.formats.html;
27
28 import java.util.List;
29
30 import javax.lang.model.element.ModuleElement;
31 import javax.lang.model.element.PackageElement;
32 import javax.lang.model.element.TypeElement;
33
34 import com.sun.source.doctree.DocTree;
35 import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
36 import jdk.javadoc.internal.doclets.formats.html.markup.Entity;
37 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
38 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
39 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
40 import jdk.javadoc.internal.doclets.formats.html.markup.Navigation;
41 import jdk.javadoc.internal.doclets.formats.html.markup.Navigation.PageMode;
42 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
43 import jdk.javadoc.internal.doclets.toolkit.AnnotationTypeWriter;
44 import jdk.javadoc.internal.doclets.toolkit.Content;
45 import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
46 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
47 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
48
49 /**
50 * Generate the Class Information Page.
51 *
52 * <p><b>This is NOT part of any supported API.
53 * If you write code that depends on this, you do so at your own risk.
54 * This code and its internal interfaces are subject to change or
55 * deletion without notice.</b>
56 *
57 * @see java.util.Collections
58 * @see java.util.List
59 * @see java.util.ArrayList
60 * @see java.util.HashMap
61 */
62 public class AnnotationTypeWriterImpl extends SubWriterHolderWriter
63 implements AnnotationTypeWriter {
64
65 protected TypeElement annotationType;
66
67 private final Navigation navBar;
68
69 /**
70 * @param configuration the configuration
71 * @param annotationType the annotation type being documented.
72 */
73 public AnnotationTypeWriterImpl(HtmlConfiguration configuration,
74 TypeElement annotationType) {
75 super(configuration, configuration.docPaths.forClass(annotationType));
76 this.annotationType = annotationType;
77 configuration.currentTypeElement = annotationType;
78 this.navBar = new Navigation(annotationType, configuration, PageMode.CLASS, path);
79 }
80
81 /**
82 * {@inheritDoc}
83 */
84 @Override
85 public Content getHeader(String header) {
86 Content headerContent = new ContentBuilder();
87 addTop(headerContent);
88 Content linkContent = getModuleLink(utils.elementUtils.getModuleOf(annotationType),
89 contents.moduleLabel);
90 navBar.setNavLinkModule(linkContent);
91 navBar.setMemberSummaryBuilder(configuration.getBuilderFactory().getMemberSummaryBuilder(this));
92 navBar.setUserHeader(getUserHeaderFooter(true));
93 headerContent.add(navBar.getContent(true));
94
95 HtmlTree div = new HtmlTree(HtmlTag.DIV);
96 div.setStyle(HtmlStyle.header);
97 if (configuration.showModules) {
98 ModuleElement mdle = configuration.docEnv.getElementUtils().getModuleOf(annotationType);
99 Content typeModuleLabel = HtmlTree.SPAN(HtmlStyle.moduleLabelInType, contents.moduleLabel);
100 Content moduleNameDiv = HtmlTree.DIV(HtmlStyle.subTitle, typeModuleLabel);
101 moduleNameDiv.add(Entity.NO_BREAK_SPACE);
102 moduleNameDiv.add(getModuleLink(mdle, new StringContent(mdle.getQualifiedName())));
103 div.add(moduleNameDiv);
104 }
105 PackageElement pkg = utils.containingPackage(annotationType);
106 if (!pkg.isUnnamed()) {
107 Content typePackageLabel = HtmlTree.SPAN(HtmlStyle.packageLabelInType, contents.packageLabel);
108 Content pkgNameDiv = HtmlTree.DIV(HtmlStyle.subTitle, typePackageLabel);
109 pkgNameDiv.add(Entity.NO_BREAK_SPACE);
110 Content pkgNameContent = getPackageLink(pkg, new StringContent(utils.getPackageName(pkg)));
111 pkgNameDiv.add(pkgNameContent);
112 div.add(pkgNameDiv);
113 }
114 LinkInfoImpl linkInfo = new LinkInfoImpl(configuration,
115 LinkInfoImpl.Kind.CLASS_HEADER, annotationType);
116 Content heading = HtmlTree.HEADING(Headings.PAGE_TITLE_HEADING, true,
117 HtmlStyle.title, new StringContent(header));
118 heading.add(getTypeParameterLinks(linkInfo));
119 div.add(heading);
120 bodyContents.setHeader(headerContent)
121 .addMainContent(MarkerComments.START_OF_CLASS_DATA)
122 .addMainContent(div);
123 return getBody(getWindowTitle(utils.getSimpleName(annotationType)));
124 }
125
126 /**
127 * {@inheritDoc}
128 */
129 @Override
130 public Content getAnnotationContentHeader() {
131 return getContentHeader();
132 }
133
134 /**
135 * {@inheritDoc}
136 */
137 @Override
138 public void addFooter() {
139 Content htmlTree = HtmlTree.FOOTER();
140 navBar.setUserFooter(getUserHeaderFooter(false));
141 htmlTree.add(navBar.getContent(false));
142 addBottom(htmlTree);
143 bodyContents.addMainContent(MarkerComments.END_OF_CLASS_DATA)
144 .setFooter(htmlTree);
145 }
146
147 /**
148 * {@inheritDoc}
149 */
150 @Override
151 public void printDocument(Content contentTree) throws DocFileIOException {
152 String description = getDescription("declaration", annotationType);
153 PackageElement pkg = utils.containingPackage(this.annotationType);
154 List<DocPath> localStylesheets = getLocalStylesheets(pkg);
155 contentTree.add(bodyContents.toContent());
156 printHtmlDocument(configuration.metakeywords.getMetaKeywords(annotationType),
157 description, localStylesheets, contentTree);
158 }
159
160 /**
161 * {@inheritDoc}
162 */
163 @Override
164 public Content getAnnotationInfoTreeHeader() {
165 return getMemberTreeHeader();
166 }
167
168 /**
169 * {@inheritDoc}
170 */
171 @Override
172 public Content getAnnotationInfo(Content annotationInfoTree) {
173 return HtmlTree.SECTION(HtmlStyle.description, annotationInfoTree);
174 }
175
176 /**
177 * {@inheritDoc}
178 */
179 @Override
180 public void addAnnotationTypeSignature(String modifiers, Content annotationInfoTree) {
181 Content hr = new HtmlTree(HtmlTag.HR);
182 annotationInfoTree.add(hr);
183 Content pre = new HtmlTree(HtmlTag.PRE);
184 addAnnotationInfo(annotationType, pre);
185 pre.add(modifiers);
186 LinkInfoImpl linkInfo = new LinkInfoImpl(configuration,
187 LinkInfoImpl.Kind.CLASS_SIGNATURE, annotationType);
188 Content annotationName = new StringContent(utils.getSimpleName(annotationType));
189 Content parameterLinks = getTypeParameterLinks(linkInfo);
190 if (configuration.linksource) {
191 addSrcLink(annotationType, annotationName, pre);
192 pre.add(parameterLinks);
193 } else {
194 Content span = HtmlTree.SPAN(HtmlStyle.memberNameLabel, annotationName);
195 span.add(parameterLinks);
196 pre.add(span);
197 }
198 annotationInfoTree.add(pre);
199 }
200
201 /**
202 * {@inheritDoc}
203 */
204 @Override
205 public void addAnnotationTypeDescription(Content annotationInfoTree) {
206 if (!configuration.nocomment) {
207 if (!utils.getFullBody(annotationType).isEmpty()) {
208 addInlineComment(annotationType, annotationInfoTree);
209 }
210 }
211 }
212
213 /**
214 * {@inheritDoc}
215 */
216 @Override
217 public void addAnnotationTypeTagInfo(Content annotationInfoTree) {
218 if (!configuration.nocomment) {
219 addTagsInfo(annotationType, annotationInfoTree);
220 }
221 }
222
223 /**
224 * {@inheritDoc}
225 */
226 @Override
227 public void addAnnotationTypeDeprecationInfo(Content annotationInfoTree) {
228 List<? extends DocTree> deprs = utils.getBlockTags(annotationType, DocTree.Kind.DEPRECATED);
229 if (utils.isDeprecated(annotationType)) {
230 CommentHelper ch = utils.getCommentHelper(annotationType);
231 Content deprLabel = HtmlTree.SPAN(HtmlStyle.deprecatedLabel, getDeprecatedPhrase(annotationType));
232 Content div = HtmlTree.DIV(HtmlStyle.deprecationBlock, deprLabel);
233 if (!deprs.isEmpty()) {
234
235 List<? extends DocTree> commentTags = ch.getDescription(configuration, deprs.get(0));
236 if (!commentTags.isEmpty()) {
237 addInlineDeprecatedComment(annotationType, deprs.get(0), div);
238 }
239 }
240 annotationInfoTree.add(div);
241 }
242 }
243
244 /**
245 * {@inheritDoc}
246 */
247 @Override
248 public TypeElement getAnnotationTypeElement() {
249 return annotationType;
250 }
251
252 /**
253 * {@inheritDoc}
254 */
255 @Override
256 public Content getMemberDetailsTree(Content contentTree) {
257 return HtmlTree.SECTION(HtmlStyle.details, contentTree)
258 .setId(SectionName.ANNOTATION_TYPE_ELEMENT_DETAIL.getName());
259 }
260 }