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