src/share/classes/com/sun/tools/doclets/formats/html/HtmlSerialFieldWriter.java

Thu, 15 Nov 2012 19:54:20 -0800

author
jjg
date
Thu, 15 Nov 2012 19:54:20 -0800
changeset 1412
400a4e8accd3
parent 1410
bfec2a1cc869
child 1735
8ea30d59ac41
permissions
-rw-r--r--

8002079: update DocFile to use a JavaFileManager
Reviewed-by: darcy

duke@1 1 /*
jjg@1357 2 * Copyright (c) 1998, 2012, Oracle and/or its affiliates. All rights reserved.
duke@1 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
duke@1 4 *
duke@1 5 * This code is free software; you can redistribute it and/or modify it
duke@1 6 * under the terms of the GNU General Public License version 2 only, as
ohair@554 7 * published by the Free Software Foundation. Oracle designates this
duke@1 8 * particular file as subject to the "Classpath" exception as provided
ohair@554 9 * by Oracle in the LICENSE file that accompanied this code.
duke@1 10 *
duke@1 11 * This code is distributed in the hope that it will be useful, but WITHOUT
duke@1 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
duke@1 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
duke@1 14 * version 2 for more details (a copy is included in the LICENSE file that
duke@1 15 * accompanied this code).
duke@1 16 *
duke@1 17 * You should have received a copy of the GNU General Public License version
duke@1 18 * 2 along with this work; if not, write to the Free Software Foundation,
duke@1 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
duke@1 20 *
ohair@554 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
ohair@554 22 * or visit www.oracle.com if you need additional information or have any
ohair@554 23 * questions.
duke@1 24 */
duke@1 25
duke@1 26 package com.sun.tools.doclets.formats.html;
duke@1 27
bpatel@233 28 import java.util.*;
bpatel@233 29
bpatel@233 30 import com.sun.javadoc.*;
jjg@1357 31 import com.sun.tools.doclets.formats.html.markup.*;
duke@1 32 import com.sun.tools.doclets.internal.toolkit.*;
duke@1 33 import com.sun.tools.doclets.internal.toolkit.taglets.*;
duke@1 34
duke@1 35 /**
duke@1 36 * Generate serialized form for serializable fields.
duke@1 37 * Documentation denoted by the tags <code>serial</code> and
duke@1 38 * <code>serialField</code> is processed.
duke@1 39 *
jjg@1359 40 * <p><b>This is NOT part of any supported API.
jjg@1359 41 * If you write code that depends on this, you do so at your own risk.
jjg@1359 42 * This code and its internal interfaces are subject to change or
jjg@1359 43 * deletion without notice.</b>
jjg@1359 44 *
duke@1 45 * @author Joe Fialli
bpatel@233 46 * @author Bhavesh Patel (Modified)
duke@1 47 */
duke@1 48 public class HtmlSerialFieldWriter extends FieldWriterImpl
duke@1 49 implements SerializedFormWriter.SerialFieldWriter {
duke@1 50 ProgramElementDoc[] members = null;
duke@1 51
duke@1 52 private boolean printedOverallAnchor = false;
duke@1 53
duke@1 54 public HtmlSerialFieldWriter(SubWriterHolderWriter writer,
duke@1 55 ClassDoc classdoc) {
duke@1 56 super(writer, classdoc);
duke@1 57 }
duke@1 58
mcimadamore@184 59 public List<FieldDoc> members(ClassDoc cd) {
jjg@910 60 return Arrays.asList(cd.serializableFields());
duke@1 61 }
duke@1 62
bpatel@766 63 /**
bpatel@766 64 * Return the header for serializable fields section.
bpatel@766 65 *
bpatel@766 66 * @return a content tree for the header
bpatel@766 67 */
bpatel@766 68 public Content getSerializableFieldsHeader() {
bpatel@766 69 HtmlTree ul = new HtmlTree(HtmlTag.UL);
bpatel@766 70 ul.addStyle(HtmlStyle.blockList);
bpatel@766 71 return ul;
duke@1 72 }
duke@1 73
duke@1 74 /**
bpatel@766 75 * Return the header for serializable fields content section.
duke@1 76 *
bpatel@766 77 * @param isLastContent true if the cotent being documented is the last content.
bpatel@766 78 * @return a content tree for the header
duke@1 79 */
bpatel@766 80 public Content getFieldsContentHeader(boolean isLastContent) {
bpatel@766 81 HtmlTree li = new HtmlTree(HtmlTag.LI);
bpatel@766 82 if (isLastContent)
bpatel@766 83 li.addStyle(HtmlStyle.blockListLast);
bpatel@766 84 else
bpatel@766 85 li.addStyle(HtmlStyle.blockList);
bpatel@766 86 return li;
duke@1 87 }
duke@1 88
duke@1 89 /**
bpatel@766 90 * Add serializable fields.
bpatel@766 91 *
bpatel@766 92 * @param heading the heading for the section
bpatel@766 93 * @param serializableFieldsTree the tree to be added to the serializable fileds
bpatel@766 94 * content tree
bpatel@766 95 * @return a content tree for the serializable fields content
bpatel@766 96 */
bpatel@766 97 public Content getSerializableFields(String heading, Content serializableFieldsTree) {
bpatel@766 98 HtmlTree li = new HtmlTree(HtmlTag.LI);
bpatel@766 99 li.addStyle(HtmlStyle.blockList);
bpatel@766 100 if (serializableFieldsTree.isValid()) {
bpatel@766 101 if (!printedOverallAnchor) {
bpatel@766 102 li.addContent(writer.getMarkerAnchor("serializedForm"));
bpatel@766 103 printedOverallAnchor = true;
bpatel@766 104 }
bpatel@766 105 Content headingContent = new StringContent(heading);
bpatel@766 106 Content serialHeading = HtmlTree.HEADING(HtmlConstants.SERIALIZED_MEMBER_HEADING,
bpatel@766 107 headingContent);
bpatel@766 108 li.addContent(serialHeading);
bpatel@766 109 li.addContent(serializableFieldsTree);
bpatel@766 110 }
bpatel@766 111 return li;
bpatel@766 112 }
bpatel@766 113
bpatel@766 114 /**
bpatel@766 115 * Add the member header.
bpatel@766 116 *
jjg@1358 117 * @param fieldType the class document to be listed
jjg@1358 118 * @param fieldTypeStr the string for the field type to be documented
bpatel@766 119 * @param fieldDimensions the dimensions of the field string to be added
jjg@1358 120 * @param fieldName name of the field to be added
bpatel@766 121 * @param contentTree the content tree to which the member header will be added
bpatel@766 122 */
bpatel@766 123 public void addMemberHeader(ClassDoc fieldType, String fieldTypeStr,
bpatel@766 124 String fieldDimensions, String fieldName, Content contentTree) {
bpatel@766 125 Content nameContent = new RawHtml(fieldName);
bpatel@766 126 Content heading = HtmlTree.HEADING(HtmlConstants.MEMBER_HEADING, nameContent);
bpatel@766 127 contentTree.addContent(heading);
bpatel@766 128 Content pre = new HtmlTree(HtmlTag.PRE);
bpatel@766 129 if (fieldType == null) {
bpatel@766 130 pre.addContent(fieldTypeStr);
bpatel@766 131 } else {
bpatel@766 132 Content fieldContent = new RawHtml(writer.getLink(new LinkInfoImpl(
jjg@1410 133 configuration, LinkInfoImpl.CONTEXT_SERIAL_MEMBER, fieldType)));
bpatel@766 134 pre.addContent(fieldContent);
bpatel@766 135 }
bpatel@766 136 pre.addContent(fieldDimensions + " ");
bpatel@766 137 pre.addContent(fieldName);
bpatel@766 138 contentTree.addContent(pre);
bpatel@766 139 }
bpatel@766 140
bpatel@766 141 /**
bpatel@766 142 * Add the deprecated information for this member.
duke@1 143 *
duke@1 144 * @param field the field to document.
bpatel@766 145 * @param contentTree the tree to which the deprecated info will be added
duke@1 146 */
bpatel@766 147 public void addMemberDeprecatedInfo(FieldDoc field, Content contentTree) {
bpatel@766 148 addDeprecatedInfo(field, contentTree);
bpatel@766 149 }
bpatel@766 150
bpatel@766 151 /**
bpatel@766 152 * Add the description text for this member.
bpatel@766 153 *
bpatel@766 154 * @param field the field to document.
bpatel@766 155 * @param contentTree the tree to which the deprecated info will be added
bpatel@766 156 */
bpatel@766 157 public void addMemberDescription(FieldDoc field, Content contentTree) {
duke@1 158 if (field.inlineTags().length > 0) {
bpatel@766 159 writer.addInlineComment(field, contentTree);
duke@1 160 }
duke@1 161 Tag[] tags = field.tags("serial");
duke@1 162 if (tags.length > 0) {
bpatel@766 163 writer.addInlineComment(field, tags[0], contentTree);
duke@1 164 }
duke@1 165 }
duke@1 166
duke@1 167 /**
bpatel@766 168 * Add the description text for this member represented by the tag.
duke@1 169 *
bpatel@766 170 * @param serialFieldTag the field to document (represented by tag)
bpatel@766 171 * @param contentTree the tree to which the deprecated info will be added
duke@1 172 */
bpatel@766 173 public void addMemberDescription(SerialFieldTag serialFieldTag, Content contentTree) {
bpatel@233 174 String serialFieldTagDesc = serialFieldTag.description().trim();
bpatel@233 175 if (!serialFieldTagDesc.isEmpty()) {
bpatel@766 176 Content serialFieldContent = new RawHtml(serialFieldTagDesc);
bpatel@766 177 Content div = HtmlTree.DIV(HtmlStyle.block, serialFieldContent);
bpatel@766 178 contentTree.addContent(div);
bpatel@233 179 }
duke@1 180 }
duke@1 181
duke@1 182 /**
bpatel@766 183 * Add the tag information for this member.
duke@1 184 *
duke@1 185 * @param field the field to document.
bpatel@766 186 * @param contentTree the tree to which the member tags info will be added
duke@1 187 */
bpatel@766 188 public void addMemberTags(FieldDoc field, Content contentTree) {
duke@1 189 TagletOutputImpl output = new TagletOutputImpl("");
jjg@1410 190 TagletWriter.genTagOuput(configuration.tagletManager, field,
jjg@1410 191 configuration.tagletManager.getCustomTags(field),
duke@1 192 writer.getTagletWriterInstance(false), output);
bpatel@233 193 String outputString = output.toString().trim();
bpatel@766 194 Content dlTags = new HtmlTree(HtmlTag.DL);
bpatel@233 195 if (!outputString.isEmpty()) {
bpatel@766 196 Content tagContent = new RawHtml(outputString);
bpatel@766 197 dlTags.addContent(tagContent);
duke@1 198 }
bpatel@766 199 contentTree.addContent(dlTags);
duke@1 200 }
bpatel@222 201
bpatel@222 202 /**
bpatel@233 203 * Check to see if overview details should be printed. If
bpatel@222 204 * nocomment option set or if there is no text to be printed
bpatel@233 205 * for deprecation info, comment or tags, do not print overview details.
bpatel@233 206 *
bpatel@233 207 * @param field the field to check overview details for.
bpatel@233 208 * @return true if overview details need to be printed
bpatel@222 209 */
bpatel@233 210 public boolean shouldPrintOverview(FieldDoc field) {
jjg@1410 211 if (!configuration.nocomment) {
bpatel@233 212 if(!field.commentText().isEmpty() ||
bpatel@233 213 writer.hasSerializationOverviewTags(field))
bpatel@222 214 return true;
bpatel@233 215 }
bpatel@233 216 if (field.tags("deprecated").length > 0)
bpatel@222 217 return true;
bpatel@222 218 return false;
bpatel@222 219 }
duke@1 220 }

mercurial