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