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 26package com.sun.tools.doclets.internal.toolkit.builders; 27 28import java.util.*; 29 30import com.sun.javadoc.*; 31import com.sun.tools.doclets.internal.toolkit.*; 32import com.sun.tools.doclets.internal.toolkit.util.*; 33 34/** 35 * Builds documentation for a constructor. 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@Deprecated 47public class ConstructorBuilder extends AbstractMemberBuilder { 48 49 /** 50 * The name of this builder. 51 */ 52 public static final String NAME = "ConstructorDetails"; 53 54 /** 55 * The index of the current field that is being documented at this point 56 * in time. 57 */ 58 private int currentConstructorIndex; 59 60 /** 61 * The class whose constructors are being documented. 62 */ 63 private final ClassDoc classDoc; 64 65 /** 66 * The visible constructors for the given class. 67 */ 68 private final VisibleMemberMap visibleMemberMap; 69 70 /** 71 * The writer to output the constructor documentation. 72 */ 73 private final ConstructorWriter writer; 74 75 /** 76 * The constructors being documented. 77 */ 78 private final List<ProgramElementDoc> constructors; 79 80 /** 81 * Construct a new ConstructorBuilder. 82 * 83 * @param context the build context. 84 * @param classDoc the class whoses members are being documented. 85 * @param writer the doclet specific writer. 86 */ 87 private ConstructorBuilder(Context context, 88 ClassDoc classDoc, 89 ConstructorWriter writer) { 90 super(context); 91 this.classDoc = classDoc; 92 this.writer = writer; 93 visibleMemberMap = 94 new VisibleMemberMap( 95 classDoc, 96 VisibleMemberMap.CONSTRUCTORS, 97 configuration); 98 constructors = new ArrayList<>(visibleMemberMap.getMembersFor(classDoc)); 99 for (ProgramElementDoc constructor : constructors) { 100 if (constructor.isProtected() || constructor.isPrivate()) { 101 writer.setFoundNonPubConstructor(true); 102 } 103 } 104 if (configuration.getMemberComparator() != null) { 105 Collections.sort(constructors,configuration.getMemberComparator()); 106 } 107 } 108 109 /** 110 * Construct a new ConstructorBuilder. 111 * 112 * @param context the build context. 113 * @param classDoc the class whoses members are being documented. 114 * @param writer the doclet specific writer. 115 */ 116 public static ConstructorBuilder getInstance(Context context, 117 ClassDoc classDoc, ConstructorWriter writer) { 118 return new ConstructorBuilder(context, classDoc, writer); 119 } 120 121 /** 122 * {@inheritDoc} 123 */ 124 public String getName() { 125 return NAME; 126 } 127 128 /** 129 * {@inheritDoc} 130 */ 131 public boolean hasMembersToDocument() { 132 return constructors.size() > 0; 133 } 134 135 /** 136 * Returns a list of constructors that will be documented for the given class. 137 * This information can be used for doclet specific documentation 138 * generation. 139 * 140 * @return a list of constructors that will be documented. 141 */ 142 public List<ProgramElementDoc> members(ClassDoc classDoc) { 143 return visibleMemberMap.getMembersFor(classDoc); 144 } 145 146 /** 147 * Return the constructor writer for this builder. 148 * 149 * @return the constructor writer for this builder. 150 */ 151 public ConstructorWriter getWriter() { 152 return writer; 153 } 154 155 /** 156 * Build the constructor documentation. 157 * 158 * @param node the XML element that specifies which components to document 159 * @param memberDetailsTree the content tree to which the documentation will be added 160 */ 161 public void buildConstructorDoc(XMLNode node, Content memberDetailsTree) { 162 if (writer == null) { 163 return; 164 } 165 int size = constructors.size(); 166 if (size > 0) { 167 Content constructorDetailsTree = writer.getConstructorDetailsTreeHeader( 168 classDoc, memberDetailsTree); 169 for (currentConstructorIndex = 0; currentConstructorIndex < size; 170 currentConstructorIndex++) { 171 Content constructorDocTree = writer.getConstructorDocTreeHeader( 172 (ConstructorDoc) constructors.get(currentConstructorIndex), 173 constructorDetailsTree); 174 buildChildren(node, constructorDocTree); 175 constructorDetailsTree.addContent(writer.getConstructorDoc( 176 constructorDocTree, (currentConstructorIndex == size - 1))); 177 } 178 memberDetailsTree.addContent( 179 writer.getConstructorDetails(constructorDetailsTree)); 180 } 181 } 182 183 /** 184 * Build the signature. 185 * 186 * @param node the XML element that specifies which components to document 187 * @param constructorDocTree the content tree to which the documentation will be added 188 */ 189 public void buildSignature(XMLNode node, Content constructorDocTree) { 190 constructorDocTree.addContent( 191 writer.getSignature( 192 (ConstructorDoc) constructors.get(currentConstructorIndex))); 193 } 194 195 /** 196 * Build the deprecation information. 197 * 198 * @param node the XML element that specifies which components to document 199 * @param constructorDocTree the content tree to which the documentation will be added 200 */ 201 public void buildDeprecationInfo(XMLNode node, Content constructorDocTree) { 202 writer.addDeprecated( 203 (ConstructorDoc) constructors.get(currentConstructorIndex), constructorDocTree); 204 } 205 206 /** 207 * Build the comments for the constructor. 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 constructorDocTree the content tree to which the documentation will be added 212 */ 213 public void buildConstructorComments(XMLNode node, Content constructorDocTree) { 214 if (!configuration.nocomment) { 215 writer.addComments( 216 (ConstructorDoc) constructors.get(currentConstructorIndex), 217 constructorDocTree); 218 } 219 } 220 221 /** 222 * Build the tag information. 223 * 224 * @param node the XML element that specifies which components to document 225 * @param constructorDocTree the content tree to which the documentation will be added 226 */ 227 public void buildTagInfo(XMLNode node, Content constructorDocTree) { 228 writer.addTags((ConstructorDoc) constructors.get(currentConstructorIndex), 229 constructorDocTree); 230 } 231} 232