Wed, 10 Oct 2012 16:48:21 -0700
8000665: fix "internal API" comments on javadoc files
Reviewed-by: darcy
1 /*
2 * Copyright (c) 2003, 2012, 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 com.sun.javadoc.*;
29 import com.sun.tools.doclets.formats.html.markup.*;
30 import com.sun.tools.doclets.internal.toolkit.*;
31 import com.sun.tools.doclets.internal.toolkit.builders.*;
32 import com.sun.tools.doclets.internal.toolkit.util.*;
34 /**
35 * Generate the Class Information Page.
36 *
37 * <p><b>This is NOT part of any supported API.
38 * If you write code that depends on this, you do so at your own risk.
39 * This code and its internal interfaces are subject to change or
40 * deletion without notice.</b>
41 *
42 * @see com.sun.javadoc.ClassDoc
43 * @see java.util.Collections
44 * @see java.util.List
45 * @see java.util.ArrayList
46 * @see java.util.HashMap
47 *
48 * @author Atul M Dambalkar
49 * @author Robert Field
50 * @author Bhavesh Patel (Modified)
51 */
52 public class AnnotationTypeWriterImpl extends SubWriterHolderWriter
53 implements AnnotationTypeWriter {
55 protected AnnotationTypeDoc annotationType;
57 protected Type prev;
59 protected Type next;
61 /**
62 * @param annotationType the annotation type being documented.
63 * @param prevType the previous class that was documented.
64 * @param nextType the next class being documented.
65 */
66 public AnnotationTypeWriterImpl (AnnotationTypeDoc annotationType,
67 Type prevType, Type nextType)
68 throws Exception {
69 super(ConfigurationImpl.getInstance(),
70 DirectoryManager.getDirectoryPath(annotationType.containingPackage()),
71 annotationType.name() + ".html",
72 DirectoryManager.getRelativePath(annotationType.containingPackage().name()));
73 this.annotationType = annotationType;
74 configuration.currentcd = annotationType.asClassDoc();
75 this.prev = prevType;
76 this.next = nextType;
77 }
79 /**
80 * Get this package link.
81 *
82 * @return a content tree for the package link
83 */
84 protected Content getNavLinkPackage() {
85 Content linkContent = getHyperLink("package-summary.html", "",
86 packageLabel);
87 Content li = HtmlTree.LI(linkContent);
88 return li;
89 }
91 /**
92 * Get the class link.
93 *
94 * @return a content tree for the class link
95 */
96 protected Content getNavLinkClass() {
97 Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, classLabel);
98 return li;
99 }
101 /**
102 * Get the class use link.
103 *
104 * @return a content tree for the class use link
105 */
106 protected Content getNavLinkClassUse() {
107 Content linkContent = getHyperLink("class-use/" + filename, "", useLabel);
108 Content li = HtmlTree.LI(linkContent);
109 return li;
110 }
112 /**
113 * Get link to previous class.
114 *
115 * @return a content tree for the previous class link
116 */
117 public Content getNavLinkPrevious() {
118 Content li;
119 if (prev != null) {
120 Content prevLink = new RawHtml(getLink(new LinkInfoImpl(
121 LinkInfoImpl.CONTEXT_CLASS, prev.asClassDoc(), "",
122 configuration.getText("doclet.Prev_Class"), true)));
123 li = HtmlTree.LI(prevLink);
124 }
125 else
126 li = HtmlTree.LI(prevclassLabel);
127 return li;
128 }
130 /**
131 * Get link to next class.
132 *
133 * @return a content tree for the next class link
134 */
135 public Content getNavLinkNext() {
136 Content li;
137 if (next != null) {
138 Content nextLink = new RawHtml(getLink(new LinkInfoImpl(
139 LinkInfoImpl.CONTEXT_CLASS, next.asClassDoc(), "",
140 configuration.getText("doclet.Next_Class"), true)));
141 li = HtmlTree.LI(nextLink);
142 }
143 else
144 li = HtmlTree.LI(nextclassLabel);
145 return li;
146 }
148 /**
149 * {@inheritDoc}
150 */
151 public Content getHeader(String header) {
152 String pkgname = (annotationType.containingPackage() != null)?
153 annotationType.containingPackage().name(): "";
154 String clname = annotationType.name();
155 Content bodyTree = getBody(true, getWindowTitle(clname));
156 addTop(bodyTree);
157 addNavLinks(true, bodyTree);
158 bodyTree.addContent(HtmlConstants.START_OF_CLASS_DATA);
159 HtmlTree div = new HtmlTree(HtmlTag.DIV);
160 div.addStyle(HtmlStyle.header);
161 if (pkgname.length() > 0) {
162 Content pkgNameContent = new StringContent(pkgname);
163 Content pkgNameDiv = HtmlTree.DIV(HtmlStyle.subTitle, pkgNameContent);
164 div.addContent(pkgNameDiv);
165 }
166 LinkInfoImpl linkInfo = new LinkInfoImpl(
167 LinkInfoImpl.CONTEXT_CLASS_HEADER, annotationType, false);
168 Content headerContent = new StringContent(header);
169 Content heading = HtmlTree.HEADING(HtmlConstants.CLASS_PAGE_HEADING, true,
170 HtmlStyle.title, headerContent);
171 heading.addContent(new RawHtml(getTypeParameterLinks(linkInfo)));
172 div.addContent(heading);
173 bodyTree.addContent(div);
174 return bodyTree;
175 }
177 /**
178 * {@inheritDoc}
179 */
180 public Content getAnnotationContentHeader() {
181 return getContentHeader();
182 }
184 /**
185 * {@inheritDoc}
186 */
187 public void addFooter(Content contentTree) {
188 contentTree.addContent(HtmlConstants.END_OF_CLASS_DATA);
189 addNavLinks(false, contentTree);
190 addBottom(contentTree);
191 }
193 /**
194 * {@inheritDoc}
195 */
196 public void printDocument(Content contentTree) {
197 printHtmlDocument(configuration.metakeywords.getMetaKeywords(annotationType),
198 true, contentTree);
199 }
201 /**
202 * {@inheritDoc}
203 */
204 public Content getAnnotationInfoTreeHeader() {
205 return getMemberTreeHeader();
206 }
208 /**
209 * {@inheritDoc}
210 */
211 public Content getAnnotationInfo(Content annotationInfoTree) {
212 return getMemberTree(HtmlStyle.description, annotationInfoTree);
213 }
215 /**
216 * {@inheritDoc}
217 */
218 public void addAnnotationTypeSignature(String modifiers, Content annotationInfoTree) {
219 annotationInfoTree.addContent(new HtmlTree(HtmlTag.BR));
220 Content pre = new HtmlTree(HtmlTag.PRE);
221 addAnnotationInfo(annotationType, pre);
222 pre.addContent(modifiers);
223 LinkInfoImpl linkInfo = new LinkInfoImpl(
224 LinkInfoImpl.CONTEXT_CLASS_SIGNATURE, annotationType, false);
225 Content annotationName = new StringContent(annotationType.name());
226 Content parameterLinks = new RawHtml(getTypeParameterLinks(linkInfo));
227 if (configuration().linksource) {
228 addSrcLink(annotationType, annotationName, pre);
229 pre.addContent(parameterLinks);
230 } else {
231 Content span = HtmlTree.SPAN(HtmlStyle.strong, annotationName);
232 span.addContent(parameterLinks);
233 pre.addContent(span);
234 }
235 annotationInfoTree.addContent(pre);
236 }
238 /**
239 * {@inheritDoc}
240 */
241 public void addAnnotationTypeDescription(Content annotationInfoTree) {
242 if(!configuration.nocomment) {
243 if (annotationType.inlineTags().length > 0) {
244 addInlineComment(annotationType, annotationInfoTree);
245 }
246 }
247 }
249 /**
250 * {@inheritDoc}
251 */
252 public void addAnnotationTypeTagInfo(Content annotationInfoTree) {
253 if(!configuration.nocomment) {
254 addTagsInfo(annotationType, annotationInfoTree);
255 }
256 }
258 /**
259 * {@inheritDoc}
260 */
261 public void addAnnotationTypeDeprecationInfo(Content annotationInfoTree) {
262 Content hr = new HtmlTree(HtmlTag.HR);
263 annotationInfoTree.addContent(hr);
264 Tag[] deprs = annotationType.tags("deprecated");
265 if (Util.isDeprecated(annotationType)) {
266 Content strong = HtmlTree.STRONG(deprecatedPhrase);
267 Content div = HtmlTree.DIV(HtmlStyle.block, strong);
268 if (deprs.length > 0) {
269 Tag[] commentTags = deprs[0].inlineTags();
270 if (commentTags.length > 0) {
271 div.addContent(getSpace());
272 addInlineDeprecatedComment(annotationType, deprs[0], div);
273 }
274 }
275 annotationInfoTree.addContent(div);
276 }
277 }
279 /**
280 * {@inheritDoc}
281 */
282 public void addAnnotationDetailsMarker(Content memberDetails) {
283 memberDetails.addContent(HtmlConstants.START_OF_ANNOTATION_TYPE_DETAILS);
284 }
286 /**
287 * {@inheritDoc}
288 */
289 protected Content getNavLinkTree() {
290 Content treeLinkContent = getHyperLink("package-tree.html",
291 "", treeLabel, "", "");
292 Content li = HtmlTree.LI(treeLinkContent);
293 return li;
294 }
296 /**
297 * Add summary details to the navigation bar.
298 *
299 * @param subDiv the content tree to which the summary detail links will be added
300 */
301 protected void addSummaryDetailLinks(Content subDiv) {
302 try {
303 Content div = HtmlTree.DIV(getNavSummaryLinks());
304 div.addContent(getNavDetailLinks());
305 subDiv.addContent(div);
306 } catch (Exception e) {
307 e.printStackTrace();
308 throw new DocletAbortException();
309 }
310 }
312 /**
313 * Get summary links for navigation bar.
314 *
315 * @return the content tree for the navigation summary links
316 */
317 protected Content getNavSummaryLinks() throws Exception {
318 Content li = HtmlTree.LI(summaryLabel);
319 li.addContent(getSpace());
320 Content ulNav = HtmlTree.UL(HtmlStyle.subNavList, li);
321 MemberSummaryBuilder memberSummaryBuilder = (MemberSummaryBuilder)
322 configuration.getBuilderFactory().getMemberSummaryBuilder(this);
323 Content liNavReq = new HtmlTree(HtmlTag.LI);
324 addNavSummaryLink(memberSummaryBuilder,
325 "doclet.navAnnotationTypeRequiredMember",
326 VisibleMemberMap.ANNOTATION_TYPE_MEMBER_REQUIRED, liNavReq);
327 addNavGap(liNavReq);
328 ulNav.addContent(liNavReq);
329 Content liNavOpt = new HtmlTree(HtmlTag.LI);
330 addNavSummaryLink(memberSummaryBuilder,
331 "doclet.navAnnotationTypeOptionalMember",
332 VisibleMemberMap.ANNOTATION_TYPE_MEMBER_OPTIONAL, liNavOpt);
333 ulNav.addContent(liNavOpt);
334 return ulNav;
335 }
337 /**
338 * Add the navigation summary link.
339 *
340 * @param builder builder for the member to be documented
341 * @param label the label for the navigation
342 * @param type type to be documented
343 * @param liNav the content tree to which the navigation summary link will be added
344 */
345 protected void addNavSummaryLink(MemberSummaryBuilder builder,
346 String label, int type, Content liNav) {
347 AbstractMemberWriter writer = ((AbstractMemberWriter) builder.
348 getMemberSummaryWriter(type));
349 if (writer == null) {
350 liNav.addContent(getResource(label));
351 } else {
352 liNav.addContent(writer.getNavSummaryLink(null,
353 ! builder.getVisibleMemberMap(type).noVisibleMembers()));
354 }
355 }
357 /**
358 * Get detail links for the navigation bar.
359 *
360 * @return the content tree for the detail links
361 */
362 protected Content getNavDetailLinks() throws Exception {
363 Content li = HtmlTree.LI(detailLabel);
364 li.addContent(getSpace());
365 Content ulNav = HtmlTree.UL(HtmlStyle.subNavList, li);
366 MemberSummaryBuilder memberSummaryBuilder = (MemberSummaryBuilder)
367 configuration.getBuilderFactory().getMemberSummaryBuilder(this);
368 AbstractMemberWriter writerOptional =
369 ((AbstractMemberWriter) memberSummaryBuilder.
370 getMemberSummaryWriter(VisibleMemberMap.ANNOTATION_TYPE_MEMBER_OPTIONAL));
371 AbstractMemberWriter writerRequired =
372 ((AbstractMemberWriter) memberSummaryBuilder.
373 getMemberSummaryWriter(VisibleMemberMap.ANNOTATION_TYPE_MEMBER_REQUIRED));
374 if (writerOptional != null){
375 Content liNavOpt = new HtmlTree(HtmlTag.LI);
376 writerOptional.addNavDetailLink(annotationType.elements().length > 0, liNavOpt);
377 ulNav.addContent(liNavOpt);
378 } else if (writerRequired != null){
379 Content liNavReq = new HtmlTree(HtmlTag.LI);
380 writerRequired.addNavDetailLink(annotationType.elements().length > 0, liNavReq);
381 ulNav.addContent(liNavReq);
382 } else {
383 Content liNav = HtmlTree.LI(getResource("doclet.navAnnotationTypeMember"));
384 ulNav.addContent(liNav);
385 }
386 return ulNav;
387 }
389 /**
390 * Add gap between navigation bar elements.
391 *
392 * @param liNav the content tree to which the gap will be added
393 */
394 protected void addNavGap(Content liNav) {
395 liNav.addContent(getSpace());
396 liNav.addContent("|");
397 liNav.addContent(getSpace());
398 }
400 /**
401 * {@inheritDoc}
402 */
403 public AnnotationTypeDoc getAnnotationTypeDoc() {
404 return annotationType;
405 }
406 }