1 /*
2  * Copyright (c) 2003, 2018, 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.PackageElement;
29 import javax.lang.model.element.TypeElement;
30 
31 import jdk.javadoc.internal.doclets.toolkit.AnnotationTypeWriter;
32 import jdk.javadoc.internal.doclets.toolkit.Content;
33 import jdk.javadoc.internal.doclets.toolkit.DocFilesHandler;
34 import jdk.javadoc.internal.doclets.toolkit.DocletException;
35 
36 
37 /**
38  * Builds the summary for a given annotation type.
39  *
40  *  <p><b>This is NOT part of any supported API.
41  *  If you write code that depends on this, you do so at your own risk.
42  *  This code and its internal interfaces are subject to change or
43  *  deletion without notice.</b>
44  *
45  * @author Jamie Ho
46  * @author Bhavesh Patel (Modified)
47  */
48 public class AnnotationTypeBuilder extends AbstractBuilder {
49 
50     /**
51      * The annotation type being documented.
52      */
53     private final TypeElement annotationType;
54 
55     /**
56      * The doclet specific writer.
57      */
58     private final AnnotationTypeWriter writer;
59 
60     /**
61      * The content tree for the annotation documentation.
62      */
63     private Content contentTree;
64 
65     /**
66      * Construct a new ClassBuilder.
67      *
68      * @param context           the build context.
69      * @param annotationTypeElement the class being documented.
70      * @param writer            the doclet specific writer.
71      */
AnnotationTypeBuilder(Context context, TypeElement annotationTypeElement, AnnotationTypeWriter writer)72     private AnnotationTypeBuilder(Context context,
73             TypeElement annotationTypeElement,
74             AnnotationTypeWriter writer) {
75         super(context);
76         this.annotationType = annotationTypeElement;
77         this.writer = writer;
78     }
79 
80     /**
81      * Construct a new AnnotationTypeBuilder.
82      *
83      * @param context           the build context.
84      * @param annotationTypeDoc the class being documented.
85      * @param writer            the doclet specific writer.
86      * @return                  an AnnotationTypeBuilder
87      */
getInstance(Context context, TypeElement annotationTypeDoc, AnnotationTypeWriter writer)88     public static AnnotationTypeBuilder getInstance(Context context,
89             TypeElement annotationTypeDoc,
90             AnnotationTypeWriter writer) {
91         return new AnnotationTypeBuilder(context, annotationTypeDoc, writer);
92     }
93 
94     /**
95      * {@inheritDoc}
96      */
97     @Override
build()98     public void build() throws DocletException {
99         buildAnnotationTypeDoc(contentTree);
100     }
101 
102     /**
103      * Build the annotation type documentation.
104      *
105      * @param contentTree the content tree to which the documentation will be added
106      * @throws DocletException if there is a problem building the documentation
107      */
buildAnnotationTypeDoc(Content contentTree)108     protected void buildAnnotationTypeDoc(Content contentTree) throws DocletException {
109         contentTree = writer.getHeader(resources.getText("doclet.AnnotationType") +
110                " " + utils.getSimpleName(annotationType));
111         Content annotationContentTree = writer.getAnnotationContentHeader();
112 
113         buildAnnotationTypeInfo(annotationContentTree);
114         buildMemberSummary(annotationContentTree);
115         buildAnnotationTypeMemberDetails(annotationContentTree);
116 
117         writer.addAnnotationContentTree(contentTree, annotationContentTree);
118         writer.addFooter(contentTree);
119         writer.printDocument(contentTree);
120         copyDocFiles();
121     }
122 
123     /**
124      * Copy the doc files for the current TypeElement if necessary.
125      *
126      * @throws DocletException if there is a problem building the documentation
127      */
copyDocFiles()128     private void copyDocFiles() throws DocletException {
129         PackageElement containingPackage = utils.containingPackage(annotationType);
130         if ((configuration.packages == null ||
131             !configuration.packages.contains(containingPackage) &&
132             !containingPackagesSeen.contains(containingPackage))){
133             //Only copy doc files dir if the containing package is not
134             //documented AND if we have not documented a class from the same
135             //package already. Otherwise, we are making duplicate copies.
136             DocFilesHandler docFilesHandler = configuration
137                     .getWriterFactory()
138                     .getDocFilesHandler(containingPackage);
139             docFilesHandler.copyDocFiles();
140             containingPackagesSeen.add(containingPackage);
141         }
142     }
143 
144     /**
145      * Build the annotation information tree documentation.
146      *
147      * @param annotationContentTree the content tree to which the documentation will be added
148      * @throws DocletException if there is a problem building the documentation
149      */
buildAnnotationTypeInfo(Content annotationContentTree)150     protected void buildAnnotationTypeInfo(Content annotationContentTree)
151             throws DocletException {
152         Content annotationInfoTree = writer.getAnnotationInfoTreeHeader();
153 
154         buildAnnotationTypeSignature(annotationInfoTree);
155         buildDeprecationInfo(annotationInfoTree);
156         buildAnnotationTypeDescription(annotationInfoTree);
157         buildAnnotationTypeTagInfo(annotationInfoTree);
158 
159         annotationContentTree.addContent(writer.getAnnotationInfo(annotationInfoTree));
160     }
161 
162     /**
163      * If this annotation is deprecated, build the appropriate information.
164      *
165      * @param annotationInfoTree the content tree to which the documentation will be added
166      */
buildDeprecationInfo(Content annotationInfoTree)167     protected void buildDeprecationInfo(Content annotationInfoTree) {
168         writer.addAnnotationTypeDeprecationInfo(annotationInfoTree);
169     }
170 
171     /**
172      * Build the signature of the current annotation type.
173      *
174      * @param annotationInfoTree the content tree to which the documentation will be added
175      */
buildAnnotationTypeSignature(Content annotationInfoTree)176     protected void buildAnnotationTypeSignature(Content annotationInfoTree) {
177         writer.addAnnotationTypeSignature(utils.modifiersToString(annotationType, true),
178                 annotationInfoTree);
179     }
180 
181     /**
182      * Build the annotation type description.
183      *
184      * @param annotationInfoTree the content tree to which the documentation will be added
185      */
buildAnnotationTypeDescription(Content annotationInfoTree)186     protected void buildAnnotationTypeDescription(Content annotationInfoTree) {
187         writer.addAnnotationTypeDescription(annotationInfoTree);
188     }
189 
190     /**
191      * Build the tag information for the current annotation type.
192      *
193      * @param annotationInfoTree the content tree to which the documentation will be added
194      */
buildAnnotationTypeTagInfo(Content annotationInfoTree)195     protected void buildAnnotationTypeTagInfo(Content annotationInfoTree) {
196         writer.addAnnotationTypeTagInfo(annotationInfoTree);
197     }
198 
199     /**
200      * Build the member summary contents of the page.
201      *
202      * @param annotationContentTree the content tree to which the documentation will be added
203      * @throws DocletException if there is a problem building the documentation
204      */
buildMemberSummary(Content annotationContentTree)205     protected void buildMemberSummary(Content annotationContentTree) throws DocletException {
206         Content memberSummaryTree = writer.getMemberTreeHeader();
207         builderFactory.getMemberSummaryBuilder(writer).build(memberSummaryTree);
208         annotationContentTree.addContent(writer.getMemberSummaryTree(memberSummaryTree));
209     }
210 
211     /**
212      * Build the member details contents of the page.
213      *
214      * @param annotationContentTree the content tree to which the documentation will be added
215      * @throws DocletException if there is a problem building the documentation
216      */
buildAnnotationTypeMemberDetails(Content annotationContentTree)217     protected void buildAnnotationTypeMemberDetails(Content annotationContentTree)
218             throws DocletException {
219         Content memberDetailsTree = writer.getMemberTreeHeader();
220 
221         buildAnnotationTypeFieldDetails(memberDetailsTree);
222         buildAnnotationTypeRequiredMemberDetails(memberDetailsTree);
223         buildAnnotationTypeOptionalMemberDetails(memberDetailsTree);
224 
225         if (memberDetailsTree.isValid()) {
226             annotationContentTree.addContent(writer.getMemberDetailsTree(memberDetailsTree));
227         }
228     }
229 
230     /**
231      * Build the annotation type field documentation.
232      *
233      * @param memberDetailsTree the content tree to which the documentation will be added
234      * @throws DocletException if there is a problem building the documentation
235      */
buildAnnotationTypeFieldDetails(Content memberDetailsTree)236     protected void buildAnnotationTypeFieldDetails(Content memberDetailsTree)
237             throws DocletException {
238         builderFactory.getAnnotationTypeFieldsBuilder(writer).build(memberDetailsTree);
239     }
240 
241     /**
242      * Build the annotation type optional member documentation.
243      *
244      * @param memberDetailsTree the content tree to which the documentation will be added
245      * @throws DocletException if there is a problem building the documentation
246      */
buildAnnotationTypeOptionalMemberDetails(Content memberDetailsTree)247     protected void buildAnnotationTypeOptionalMemberDetails(Content memberDetailsTree)
248             throws DocletException {
249         builderFactory.getAnnotationTypeOptionalMemberBuilder(writer).build(memberDetailsTree);
250     }
251 
252     /**
253      * Build the annotation type required member documentation.
254      *
255      * @param memberDetailsTree the content tree to which the documentation will be added
256      * @throws DocletException if there is a problem building the documentation
257      */
buildAnnotationTypeRequiredMemberDetails(Content memberDetailsTree)258     protected void buildAnnotationTypeRequiredMemberDetails(Content memberDetailsTree)
259             throws DocletException {
260         builderFactory.getAnnotationTypeRequiredMemberBuilder(writer).build(memberDetailsTree);
261     }
262 }
263