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 java.util.*; 29 30import javax.lang.model.element.Element; 31import javax.lang.model.element.ExecutableElement; 32import javax.lang.model.element.TypeElement; 33 34import jdk.javadoc.internal.doclets.toolkit.Configuration; 35import jdk.javadoc.internal.doclets.toolkit.ConstructorWriter; 36import jdk.javadoc.internal.doclets.toolkit.Content; 37import jdk.javadoc.internal.doclets.toolkit.DocletException; 38import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap; 39 40 41/** 42 * Builds documentation for a constructor. 43 * 44 * <p><b>This is NOT part of any supported API. 45 * If you write code that depends on this, you do so at your own risk. 46 * This code and its internal interfaces are subject to change or 47 * deletion without notice.</b> 48 * 49 * @author Jamie Ho 50 * @author Bhavesh Patel (Modified) 51 */ 52public class ConstructorBuilder extends AbstractMemberBuilder { 53 54 /** 55 * The name of this builder. 56 */ 57 public static final String NAME = "ConstructorDetails"; 58 59 /** 60 * The current constructor that is being documented at this point in time. 61 */ 62 private ExecutableElement currentConstructor; 63 64 /** 65 * The class whose constructors are being documented. 66 */ 67 private final TypeElement typeElement; 68 69 /** 70 * The visible constructors for the given class. 71 */ 72 private final VisibleMemberMap visibleMemberMap; 73 74 /** 75 * The writer to output the constructor documentation. 76 */ 77 private final ConstructorWriter writer; 78 79 /** 80 * The constructors being documented. 81 */ 82 private final List<Element> constructors; 83 84 /** 85 * Construct a new ConstructorBuilder. 86 * 87 * @param context the build context. 88 * @param typeElement the class whoses members are being documented. 89 * @param writer the doclet specific writer. 90 */ 91 private ConstructorBuilder(Context context, 92 TypeElement typeElement, 93 ConstructorWriter writer) { 94 super(context); 95 this.typeElement = typeElement; 96 this.writer = writer; 97 visibleMemberMap = configuration.getVisibleMemberMap(typeElement, 98 VisibleMemberMap.Kind.CONSTRUCTORS); 99 constructors = visibleMemberMap.getMembers(typeElement); 100 for (Element ctor : constructors) { 101 if (utils.isProtected(ctor) || utils.isPrivate(ctor)) { 102 writer.setFoundNonPubConstructor(true); 103 } 104 } 105 } 106 107 /** 108 * Construct a new ConstructorBuilder. 109 * 110 * @param context the build context. 111 * @param typeElement the class whoses members are being documented. 112 * @param writer the doclet specific writer. 113 * @return the new ConstructorBuilder 114 */ 115 public static ConstructorBuilder getInstance(Context context, 116 TypeElement typeElement, ConstructorWriter writer) { 117 return new ConstructorBuilder(context, typeElement, writer); 118 } 119 120 /** 121 * {@inheritDoc} 122 */ 123 @Override 124 public String getName() { 125 return NAME; 126 } 127 128 /** 129 * {@inheritDoc} 130 */ 131 @Override 132 public boolean hasMembersToDocument() { 133 return !constructors.isEmpty(); 134 } 135 136 /** 137 * Return the constructor writer for this builder. 138 * 139 * @return the constructor writer for this builder. 140 */ 141 public ConstructorWriter getWriter() { 142 return writer; 143 } 144 145 /** 146 * Build the constructor documentation. 147 * 148 * @param node the XML element that specifies which components to document 149 * @param memberDetailsTree the content tree to which the documentation will be added 150 * @throws DocletException is there is a problem while building the documentation 151 */ 152 public void buildConstructorDoc(XMLNode node, Content memberDetailsTree) throws DocletException { 153 if (writer == null) { 154 return; 155 } 156 if (hasMembersToDocument()) { 157 Content constructorDetailsTree = writer.getConstructorDetailsTreeHeader(typeElement, 158 memberDetailsTree); 159 160 Element lastElement = constructors.get(constructors.size() - 1); 161 for (Element contructor : constructors) { 162 currentConstructor = (ExecutableElement)contructor; 163 Content constructorDocTree = writer.getConstructorDocTreeHeader(currentConstructor, constructorDetailsTree); 164 buildChildren(node, constructorDocTree); 165 constructorDetailsTree.addContent(writer.getConstructorDoc(constructorDocTree, 166 currentConstructor == lastElement)); 167 } 168 memberDetailsTree.addContent( 169 writer.getConstructorDetails(constructorDetailsTree)); 170 } 171 } 172 173 /** 174 * Build the signature. 175 * 176 * @param node the XML element that specifies which components to document 177 * @param constructorDocTree the content tree to which the documentation will be added 178 */ 179 public void buildSignature(XMLNode node, Content constructorDocTree) { 180 constructorDocTree.addContent(writer.getSignature(currentConstructor)); 181 } 182 183 /** 184 * Build the deprecation information. 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 buildDeprecationInfo(XMLNode node, Content constructorDocTree) { 190 writer.addDeprecated(currentConstructor, constructorDocTree); 191 } 192 193 /** 194 * Build the comments for the constructor. Do nothing if 195 * {@link Configuration#nocomment} is set to true. 196 * 197 * @param node the XML element that specifies which components to document 198 * @param constructorDocTree the content tree to which the documentation will be added 199 */ 200 public void buildConstructorComments(XMLNode node, Content constructorDocTree) { 201 if (!configuration.nocomment) { 202 writer.addComments(currentConstructor, constructorDocTree); 203 } 204 } 205 206 /** 207 * Build the tag information. 208 * 209 * @param node the XML element that specifies which components to document 210 * @param constructorDocTree the content tree to which the documentation will be added 211 */ 212 public void buildTagInfo(XMLNode node, Content constructorDocTree) { 213 writer.addTags(currentConstructor, constructorDocTree); 214 } 215} 216