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.BaseConfiguration; 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 current constructor that is being documented at this point in time. 56 */ 57 private ExecutableElement currentConstructor; 58 59 /** 60 * The class whose constructors are being documented. 61 */ 62 private final TypeElement typeElement; 63 64 /** 65 * The visible constructors for the given class. 66 */ 67 private final VisibleMemberMap visibleMemberMap; 68 69 /** 70 * The writer to output the constructor documentation. 71 */ 72 private final ConstructorWriter writer; 73 74 /** 75 * The constructors being documented. 76 */ 77 private final List<Element> constructors; 78 79 /** 80 * Construct a new ConstructorBuilder. 81 * 82 * @param context the build context. 83 * @param typeElement the class whose members are being documented. 84 * @param writer the doclet specific writer. 85 */ 86 private ConstructorBuilder(Context context, 87 TypeElement typeElement, 88 ConstructorWriter writer) { 89 super(context); 90 this.typeElement = typeElement; 91 this.writer = writer; 92 visibleMemberMap = configuration.getVisibleMemberMap(typeElement, 93 VisibleMemberMap.Kind.CONSTRUCTORS); 94 constructors = visibleMemberMap.getMembers(typeElement); 95 for (Element ctor : constructors) { 96 if (utils.isProtected(ctor) || utils.isPrivate(ctor)) { 97 writer.setFoundNonPubConstructor(true); 98 } 99 } 100 } 101 102 /** 103 * Construct a new ConstructorBuilder. 104 * 105 * @param context the build context. 106 * @param typeElement the class whose members are being documented. 107 * @param writer the doclet specific writer. 108 * @return the new ConstructorBuilder 109 */ 110 public static ConstructorBuilder getInstance(Context context, 111 TypeElement typeElement, ConstructorWriter writer) { 112 return new ConstructorBuilder(context, typeElement, writer); 113 } 114 115 /** 116 * {@inheritDoc} 117 */ 118 @Override 119 public boolean hasMembersToDocument() { 120 return !constructors.isEmpty(); 121 } 122 123 /** 124 * Return the constructor writer for this builder. 125 * 126 * @return the constructor writer for this builder. 127 */ 128 public ConstructorWriter getWriter() { 129 return writer; 130 } 131 132 /** 133 * {@inheritDoc} 134 */ 135 @Override 136 public void build(Content contentTree) throws DocletException { 137 buildConstructorDoc(contentTree); 138 } 139 140 /** 141 * Build the constructor documentation. 142 * 143 * @param memberDetailsTree the content tree to which the documentation will be added 144 * @throws DocletException is there is a problem while building the documentation 145 */ 146 protected void buildConstructorDoc(Content memberDetailsTree) throws DocletException { 147 if (writer == null) { 148 return; 149 } 150 if (hasMembersToDocument()) { 151 Content constructorDetailsTree = writer.getConstructorDetailsTreeHeader(typeElement, 152 memberDetailsTree); 153 154 Element lastElement = constructors.get(constructors.size() - 1); 155 for (Element contructor : constructors) { 156 currentConstructor = (ExecutableElement)contructor; 157 Content constructorDocTree = writer.getConstructorDocTreeHeader(currentConstructor, constructorDetailsTree); 158 159 buildSignature(constructorDocTree); 160 buildDeprecationInfo(constructorDocTree); 161 buildConstructorComments(constructorDocTree); 162 buildTagInfo(constructorDocTree); 163 164 constructorDetailsTree.addContent(writer.getConstructorDoc(constructorDocTree, 165 currentConstructor == lastElement)); 166 } 167 memberDetailsTree.addContent( 168 writer.getConstructorDetails(constructorDetailsTree)); 169 } 170 } 171 172 /** 173 * Build the signature. 174 * 175 * @param constructorDocTree the content tree to which the documentation will be added 176 */ 177 protected void buildSignature(Content constructorDocTree) { 178 constructorDocTree.addContent(writer.getSignature(currentConstructor)); 179 } 180 181 /** 182 * Build the deprecation information. 183 * 184 * @param constructorDocTree the content tree to which the documentation will be added 185 */ 186 protected void buildDeprecationInfo(Content constructorDocTree) { 187 writer.addDeprecated(currentConstructor, constructorDocTree); 188 } 189 190 /** 191 * Build the comments for the constructor. Do nothing if 192 * {@link BaseConfiguration#nocomment} is set to true. 193 * 194 * @param constructorDocTree the content tree to which the documentation will be added 195 */ 196 protected void buildConstructorComments(Content constructorDocTree) { 197 if (!configuration.nocomment) { 198 writer.addComments(currentConstructor, constructorDocTree); 199 } 200 } 201 202 /** 203 * Build the tag information. 204 * 205 * @param constructorDocTree the content tree to which the documentation will be added 206 */ 207 protected void buildTagInfo(Content constructorDocTree) { 208 writer.addTags(currentConstructor, constructorDocTree); 209 } 210} 211