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