1 /* 2 * Copyright (c) 2003, 2021, 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 jdk.javadoc.internal.doclets.toolkit.builders; 27 28 import java.util.*; 29 30 import javax.lang.model.element.Element; 31 import javax.lang.model.element.TypeElement; 32 import javax.lang.model.element.VariableElement; 33 34 import jdk.javadoc.internal.doclets.toolkit.BaseOptions; 35 import jdk.javadoc.internal.doclets.toolkit.Content; 36 import jdk.javadoc.internal.doclets.toolkit.DocletException; 37 import jdk.javadoc.internal.doclets.toolkit.EnumConstantWriter; 38 39 import static jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable.Kind.*; 40 41 /** 42 * Builds documentation for a enum constants. 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 public class EnumConstantBuilder extends AbstractMemberBuilder { 50 51 /** 52 * The writer to output the enum constants documentation. 53 */ 54 private final EnumConstantWriter writer; 55 56 /** 57 * The set of enum constants being documented. 58 */ 59 private final List<? extends Element> enumConstants; 60 61 /** 62 * The current enum constant that is being documented at this point 63 * in time. 64 */ 65 private VariableElement currentElement; 66 67 /** 68 * Construct a new EnumConstantsBuilder. 69 * 70 * @param context the build context. 71 * @param typeElement the class whose members are being documented. 72 * @param writer the doclet specific writer. 73 */ EnumConstantBuilder(Context context, TypeElement typeElement, EnumConstantWriter writer)74 private EnumConstantBuilder(Context context, 75 TypeElement typeElement, EnumConstantWriter writer) { 76 super(context, typeElement); 77 this.writer = Objects.requireNonNull(writer); 78 enumConstants = getVisibleMembers(ENUM_CONSTANTS); 79 } 80 81 /** 82 * Construct a new EnumConstantsBuilder. 83 * 84 * @param context the build context. 85 * @param typeElement the class whose members are being documented. 86 * @param writer the doclet specific writer. 87 * @return the new EnumConstantsBuilder 88 */ getInstance(Context context, TypeElement typeElement, EnumConstantWriter writer)89 public static EnumConstantBuilder getInstance(Context context, 90 TypeElement typeElement, EnumConstantWriter writer) { 91 return new EnumConstantBuilder(context, typeElement, writer); 92 } 93 94 /** 95 * Returns whether or not there are members to document. 96 * 97 * @return whether or not there are members to document 98 */ 99 @Override hasMembersToDocument()100 public boolean hasMembersToDocument() { 101 return !enumConstants.isEmpty(); 102 } 103 104 @Override build(Content contentTree)105 public void build(Content contentTree) throws DocletException { 106 buildEnumConstant(contentTree); 107 } 108 109 /** 110 * Build the enum constant documentation. 111 * 112 * @param detailsList the content tree to which the documentation will be added 113 * @throws DocletException is there is a problem while building the documentation 114 */ buildEnumConstant(Content detailsList)115 protected void buildEnumConstant(Content detailsList) throws DocletException { 116 if (hasMembersToDocument()) { 117 Content enumConstantsDetailsTreeHeader = writer.getEnumConstantsDetailsTreeHeader(typeElement, 118 detailsList); 119 Content memberList = writer.getMemberList(); 120 121 for (Element enumConstant : enumConstants) { 122 currentElement = (VariableElement)enumConstant; 123 Content enumConstantsTree = writer.getEnumConstantsTreeHeader(currentElement, 124 memberList); 125 126 buildSignature(enumConstantsTree); 127 buildDeprecationInfo(enumConstantsTree); 128 buildPreviewInfo(enumConstantsTree); 129 buildEnumConstantComments(enumConstantsTree); 130 buildTagInfo(enumConstantsTree); 131 132 memberList.add(writer.getMemberListItem(enumConstantsTree)); 133 } 134 Content enumConstantDetails = writer.getEnumConstantsDetails( 135 enumConstantsDetailsTreeHeader, memberList); 136 detailsList.add(enumConstantDetails); 137 } 138 } 139 140 /** 141 * Build the signature. 142 * 143 * @param enumConstantsTree the content tree to which the documentation will be added 144 */ buildSignature(Content enumConstantsTree)145 protected void buildSignature(Content enumConstantsTree) { 146 enumConstantsTree.add(writer.getSignature(currentElement)); 147 } 148 149 /** 150 * Build the deprecation information. 151 * 152 * @param enumConstantsTree the content tree to which the documentation will be added 153 */ buildDeprecationInfo(Content enumConstantsTree)154 protected void buildDeprecationInfo(Content enumConstantsTree) { 155 writer.addDeprecated(currentElement, enumConstantsTree); 156 } 157 158 /** 159 * Build the preview information. 160 * 161 * @param enumConstantsTree the content tree to which the documentation will be added 162 */ buildPreviewInfo(Content enumConstantsTree)163 protected void buildPreviewInfo(Content enumConstantsTree) { 164 writer.addPreview(currentElement, enumConstantsTree); 165 } 166 167 /** 168 * Build the comments for the enum constant. Do nothing if 169 * {@link BaseOptions#noComment()} is set to true. 170 * 171 * @param enumConstantsTree the content tree to which the documentation will be added 172 */ buildEnumConstantComments(Content enumConstantsTree)173 protected void buildEnumConstantComments(Content enumConstantsTree) { 174 if (!options.noComment()) { 175 writer.addComments(currentElement, enumConstantsTree); 176 } 177 } 178 179 /** 180 * Build the tag information. 181 * 182 * @param enumConstantsTree the content tree to which the documentation will be added 183 */ buildTagInfo(Content enumConstantsTree)184 protected void buildTagInfo(Content enumConstantsTree) { 185 writer.addTags(currentElement, enumConstantsTree); 186 } 187 188 /** 189 * Return the enum constant writer for this builder. 190 * 191 * @return the enum constant writer for this builder. 192 */ getWriter()193 public EnumConstantWriter getWriter() { 194 return writer; 195 } 196 } 197