HtmlSerialFieldWriter.java revision 3692:87b48a8fb3cf
1/* 2 * Copyright (c) 1998, 2016, 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.formats.html; 27 28import java.util.*; 29 30import javax.lang.model.element.TypeElement; 31import javax.lang.model.element.VariableElement; 32 33import com.sun.source.doctree.DocTree; 34 35import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder; 36import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants; 37import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; 38import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag; 39import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; 40import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml; 41import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; 42import jdk.javadoc.internal.doclets.toolkit.Content; 43import jdk.javadoc.internal.doclets.toolkit.SerializedFormWriter; 44import jdk.javadoc.internal.doclets.toolkit.taglets.TagletWriter; 45import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper; 46 47/** 48 * Generate serialized form for serializable fields. 49 * Documentation denoted by the tags <code>serial</code> and 50 * <code>serialField</code> is processed. 51 * 52 * <p><b>This is NOT part of any supported API. 53 * If you write code that depends on this, you do so at your own risk. 54 * This code and its internal interfaces are subject to change or 55 * deletion without notice.</b> 56 * 57 * @author Joe Fialli 58 * @author Bhavesh Patel (Modified) 59 */ 60public class HtmlSerialFieldWriter extends FieldWriterImpl 61 implements SerializedFormWriter.SerialFieldWriter { 62 63 public HtmlSerialFieldWriter(SubWriterHolderWriter writer, TypeElement typeElement) { 64 super(writer, typeElement); 65 } 66 67 public SortedSet<VariableElement> members(TypeElement te) { 68 return utils.serializableFields(te); 69 } 70 71 /** 72 * Return the header for serializable fields section. 73 * 74 * @return a content tree for the header 75 */ 76 public Content getSerializableFieldsHeader() { 77 HtmlTree ul = new HtmlTree(HtmlTag.UL); 78 ul.addStyle(HtmlStyle.blockList); 79 return ul; 80 } 81 82 /** 83 * Return the header for serializable fields content section. 84 * 85 * @param isLastContent true if the cotent being documented is the last content. 86 * @return a content tree for the header 87 */ 88 public Content getFieldsContentHeader(boolean isLastContent) { 89 HtmlTree li = new HtmlTree(HtmlTag.LI); 90 if (isLastContent) 91 li.addStyle(HtmlStyle.blockListLast); 92 else 93 li.addStyle(HtmlStyle.blockList); 94 return li; 95 } 96 97 /** 98 * Add serializable fields. 99 * 100 * @param heading the heading for the section 101 * @param serializableFieldsTree the tree to be added to the serializable fileds 102 * content tree 103 * @return a content tree for the serializable fields content 104 */ 105 public Content getSerializableFields(String heading, Content serializableFieldsTree) { 106 HtmlTree li = new HtmlTree(HtmlTag.LI); 107 li.addStyle(HtmlStyle.blockList); 108 if (serializableFieldsTree.isValid()) { 109 Content headingContent = new StringContent(heading); 110 Content serialHeading = HtmlTree.HEADING(HtmlConstants.SERIALIZED_MEMBER_HEADING, 111 headingContent); 112 li.addContent(serialHeading); 113 li.addContent(serializableFieldsTree); 114 } 115 return li; 116 } 117 118 /** 119 * Add the member header. 120 * 121 * @param fieldType the class document to be listed 122 * @param fieldTypeStr the string for the field type to be documented 123 * @param fieldDimensions the dimensions of the field string to be added 124 * @param fieldName name of the field to be added 125 * @param contentTree the content tree to which the member header will be added 126 */ 127 public void addMemberHeader(TypeElement fieldType, String fieldTypeStr, 128 String fieldDimensions, String fieldName, Content contentTree) { 129 Content nameContent = new RawHtml(fieldName); 130 Content heading = HtmlTree.HEADING(HtmlConstants.MEMBER_HEADING, nameContent); 131 contentTree.addContent(heading); 132 Content pre = new HtmlTree(HtmlTag.PRE); 133 if (fieldType == null) { 134 pre.addContent(fieldTypeStr); 135 } else { 136 Content fieldContent = writer.getLink(new LinkInfoImpl( 137 configuration, LinkInfoImpl.Kind.SERIAL_MEMBER, fieldType)); 138 pre.addContent(fieldContent); 139 } 140 pre.addContent(fieldDimensions + " "); 141 pre.addContent(fieldName); 142 contentTree.addContent(pre); 143 } 144 145 /** 146 * Add the deprecated information for this member. 147 * 148 * @param field the field to document. 149 * @param contentTree the tree to which the deprecated info will be added 150 */ 151 public void addMemberDeprecatedInfo(VariableElement field, Content contentTree) { 152 addDeprecatedInfo(field, contentTree); 153 } 154 155 /** 156 * Add the description text for this member. 157 * 158 * @param field the field to document. 159 * @param contentTree the tree to which the deprecated info will be added 160 */ 161 public void addMemberDescription(VariableElement field, Content contentTree) { 162 if (!utils.getFullBody(field).isEmpty()) { 163 writer.addInlineComment(field, contentTree); 164 } 165 List<? extends DocTree> tags = utils.getBlockTags(field, DocTree.Kind.SERIAL); 166 if (!tags.isEmpty()) { 167 writer.addInlineComment(field, tags.get(0), contentTree); 168 } 169 } 170 171 /** 172 * Add the description text for this member represented by the tag. 173 * 174 * @param serialFieldTag the field to document (represented by tag) 175 * @param contentTree the tree to which the deprecated info will be added 176 */ 177 public void addMemberDescription(VariableElement field, DocTree serialFieldTag, Content contentTree) { 178 CommentHelper ch = utils.getCommentHelper(field); 179 List<? extends DocTree> description = ch.getDescription(configuration, serialFieldTag); 180 if (!description.isEmpty()) { 181 Content serialFieldContent = new RawHtml(ch.getText(description)); 182 Content div = HtmlTree.DIV(HtmlStyle.block, serialFieldContent); 183 contentTree.addContent(div); 184 } 185 } 186 187 /** 188 * Add the tag information for this member. 189 * 190 * @param field the field to document. 191 * @param contentTree the tree to which the member tags info will be added 192 */ 193 public void addMemberTags(VariableElement field, Content contentTree) { 194 Content tagContent = new ContentBuilder(); 195 TagletWriter.genTagOutput(configuration.tagletManager, field, 196 configuration.tagletManager.getCustomTaglets(field), 197 writer.getTagletWriterInstance(false), tagContent); 198 Content dlTags = new HtmlTree(HtmlTag.DL); 199 dlTags.addContent(tagContent); 200 contentTree.addContent(dlTags); // TODO: what if empty? 201 } 202 203 /** 204 * Check to see if overview details should be printed. If 205 * nocomment option set or if there is no text to be printed 206 * for deprecation info, comment or tags, do not print overview details. 207 * 208 * @param field the field to check overview details for. 209 * @return true if overview details need to be printed 210 */ 211 public boolean shouldPrintOverview(VariableElement field) { 212 if (!configuration.nocomment) { 213 if(!utils.getFullBody(field).isEmpty() || 214 writer.hasSerializationOverviewTags(field)) 215 return true; 216 } 217 if (utils.isDeprecated(field)) 218 return true; 219 return false; 220 } 221} 222