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