1 /* 2 * Copyright (c) 2003, 2013, 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 com.sun.tools.doclets.internal.toolkit.builders; 27 28 import java.util.*; 29 30 import com.sun.javadoc.*; 31 import com.sun.tools.doclets.internal.toolkit.*; 32 import com.sun.tools.doclets.internal.toolkit.util.*; 33 34 /** 35 * Builds documentation for required annotation type members. 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 * @author Jamie Ho 43 * @author Bhavesh Patel (Modified) 44 * @since 1.5 45 */ 46 public class AnnotationTypeRequiredMemberBuilder extends AbstractMemberBuilder { 47 48 /** 49 * The annotation type whose members are being documented. 50 */ 51 protected ClassDoc classDoc; 52 53 /** 54 * The visible members for the given class. 55 */ 56 protected VisibleMemberMap visibleMemberMap; 57 58 /** 59 * The writer to output the member documentation. 60 */ 61 protected AnnotationTypeRequiredMemberWriter writer; 62 63 /** 64 * The list of members being documented. 65 */ 66 protected List<ProgramElementDoc> members; 67 68 /** 69 * The index of the current member that is being documented at this point 70 * in time. 71 */ 72 protected int currentMemberIndex; 73 74 /** 75 * Construct a new AnnotationTypeRequiredMemberBuilder. 76 * 77 * @param context the build context. 78 * @param classDoc the class whose members are being documented. 79 * @param writer the doclet specific writer. 80 */ 81 protected AnnotationTypeRequiredMemberBuilder(Context context, 82 ClassDoc classDoc, 83 AnnotationTypeRequiredMemberWriter writer, 84 int memberType) { 85 super(context); 86 this.classDoc = classDoc; 87 this.writer = writer; 88 this.visibleMemberMap = new VisibleMemberMap(classDoc, memberType, 89 configuration); 90 this.members = new ArrayList<>(this.visibleMemberMap.getMembersFor(classDoc)); 91 if (configuration.getMemberComparator() != null) { 92 Collections.sort(this.members, configuration.getMemberComparator()); 93 } 94 } 95 96 97 /** 98 * Construct a new AnnotationTypeMemberBuilder. 99 * 100 * @param context the build context. 101 * @param classDoc the class whose members are being documented. 102 * @param writer the doclet specific writer. 103 */ 104 public static AnnotationTypeRequiredMemberBuilder getInstance( 105 Context context, ClassDoc classDoc, 106 AnnotationTypeRequiredMemberWriter writer) { 107 return new AnnotationTypeRequiredMemberBuilder(context, classDoc, 108 writer, 109 VisibleMemberMap.ANNOTATION_TYPE_MEMBER_REQUIRED); 110 } 111 112 /** 113 * {@inheritDoc} 114 */ 115 public String getName() { 116 return "AnnotationTypeRequiredMemberDetails"; 117 } 118 119 /** 120 * Returns a list of members that will be documented for the given class. 121 * This information can be used for doclet specific documentation 122 * generation. 123 * 124 * @param classDoc the {@link ClassDoc} we want to check. 125 * @return a list of members that will be documented. 126 */ 127 public List<ProgramElementDoc> members(ClassDoc classDoc) { 128 return visibleMemberMap.getMembersFor(classDoc); 129 } 130 131 /** 132 * Returns the visible member map for the members of this class. 133 * 134 * @return the visible member map for the members of this class. 135 */ 136 public VisibleMemberMap getVisibleMemberMap() { 137 return visibleMemberMap; 138 } 139 140 /** 141 * summaryOrder.size() 142 */ 143 public boolean hasMembersToDocument() { 144 return members.size() > 0; 145 } 146 147 /** 148 * Build the annotation type required member documentation. 149 * 150 * @param node the XML element that specifies which components to document 151 * @param memberDetailsTree the content tree to which the documentation will be added 152 */ 153 public void buildAnnotationTypeRequiredMember(XMLNode node, Content memberDetailsTree) { 154 buildAnnotationTypeMember(node, memberDetailsTree); 155 } 156 157 /** 158 * Build the member documentation. 159 * 160 * @param node the XML element that specifies which components to document 161 * @param memberDetailsTree the content tree to which the documentation will be added 162 */ 163 public void buildAnnotationTypeMember(XMLNode node, Content memberDetailsTree) { 164 if (writer == null) { 165 return; 166 } 167 int size = members.size(); 168 if (size > 0) { 169 writer.addAnnotationDetailsMarker(memberDetailsTree); 170 for (currentMemberIndex = 0; currentMemberIndex < size; 171 currentMemberIndex++) { 172 Content detailsTree = writer.getMemberTreeHeader(); 173 writer.addAnnotationDetailsTreeHeader(classDoc, detailsTree); 174 Content annotationDocTree = writer.getAnnotationDocTreeHeader( 175 (MemberDoc) members.get(currentMemberIndex), detailsTree); 176 buildChildren(node, annotationDocTree); 177 detailsTree.addContent(writer.getAnnotationDoc( 178 annotationDocTree, (currentMemberIndex == size - 1))); 179 memberDetailsTree.addContent(writer.getAnnotationDetails(detailsTree)); 180 } 181 } 182 } 183 184 /** 185 * Build the signature. 186 * 187 * @param node the XML element that specifies which components to document 188 * @param annotationDocTree the content tree to which the documentation will be added 189 */ 190 public void buildSignature(XMLNode node, Content annotationDocTree) { 191 annotationDocTree.addContent( 192 writer.getSignature((MemberDoc) members.get(currentMemberIndex))); 193 } 194 195 /** 196 * Build the deprecation information. 197 * 198 * @param node the XML element that specifies which components to document 199 * @param annotationDocTree the content tree to which the documentation will be added 200 */ 201 public void buildDeprecationInfo(XMLNode node, Content annotationDocTree) { 202 writer.addDeprecated((MemberDoc) members.get(currentMemberIndex), 203 annotationDocTree); 204 } 205 206 /** 207 * Build the comments for the member. Do nothing if 208 * {@link Configuration#nocomment} is set to true. 209 * 210 * @param node the XML element that specifies which components to document 211 * @param annotationDocTree the content tree to which the documentation will be added 212 */ 213 public void buildMemberComments(XMLNode node, Content annotationDocTree) { 214 if(! configuration.nocomment){ 215 writer.addComments((MemberDoc) members.get(currentMemberIndex), 216 annotationDocTree); 217 } 218 } 219 220 /** 221 * Build the tag information. 222 * 223 * @param node the XML element that specifies which components to document 224 * @param annotationDocTree the content tree to which the documentation will be added 225 */ 226 public void buildTagInfo(XMLNode node, Content annotationDocTree) { 227 writer.addTags((MemberDoc) members.get(currentMemberIndex), 228 annotationDocTree); 229 } 230 231 /** 232 * Return the annotation type required member writer for this builder. 233 * 234 * @return the annotation type required member constant writer for this 235 * builder. 236 */ 237 public AnnotationTypeRequiredMemberWriter getWriter() { 238 return writer; 239 } 240 }