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

Wed, 10 Oct 2012 16:48:21 -0700

author
jjg
date
Wed, 10 Oct 2012 16:48:21 -0700
changeset 1359
25e14ad23cef
parent 1358
fc123bdeddb8
child 1365
2013982bee34
permissions
-rw-r--r--

8000665: fix "internal API" comments on javadoc files
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
duke@1 63 protected void printTypeLinkNoDimension(Type type) {
duke@1 64 ClassDoc cd = type.asClassDoc();
duke@1 65 //Linking to package private classes in serialized for causes
duke@1 66 //broken links. Don't link to them.
duke@1 67 if (type.isPrimitive() || cd.isPackagePrivate()) {
duke@1 68 print(type.typeName());
duke@1 69 } else {
duke@1 70 writer.printLink(new LinkInfoImpl(
duke@1 71 LinkInfoImpl.CONTEXT_SERIAL_MEMBER, type));
duke@1 72 }
duke@1 73 }
duke@1 74
bpatel@766 75 /**
bpatel@766 76 * Return the header for serializable fields section.
bpatel@766 77 *
bpatel@766 78 * @return a content tree for the header
bpatel@766 79 */
bpatel@766 80 public Content getSerializableFieldsHeader() {
bpatel@766 81 HtmlTree ul = new HtmlTree(HtmlTag.UL);
bpatel@766 82 ul.addStyle(HtmlStyle.blockList);
bpatel@766 83 return ul;
duke@1 84 }
duke@1 85
duke@1 86 /**
bpatel@766 87 * Return the header for serializable fields content section.
duke@1 88 *
bpatel@766 89 * @param isLastContent true if the cotent being documented is the last content.
bpatel@766 90 * @return a content tree for the header
duke@1 91 */
bpatel@766 92 public Content getFieldsContentHeader(boolean isLastContent) {
bpatel@766 93 HtmlTree li = new HtmlTree(HtmlTag.LI);
bpatel@766 94 if (isLastContent)
bpatel@766 95 li.addStyle(HtmlStyle.blockListLast);
bpatel@766 96 else
bpatel@766 97 li.addStyle(HtmlStyle.blockList);
bpatel@766 98 return li;
duke@1 99 }
duke@1 100
duke@1 101 /**
bpatel@766 102 * Add serializable fields.
bpatel@766 103 *
bpatel@766 104 * @param heading the heading for the section
bpatel@766 105 * @param serializableFieldsTree the tree to be added to the serializable fileds
bpatel@766 106 * content tree
bpatel@766 107 * @return a content tree for the serializable fields content
bpatel@766 108 */
bpatel@766 109 public Content getSerializableFields(String heading, Content serializableFieldsTree) {
bpatel@766 110 HtmlTree li = new HtmlTree(HtmlTag.LI);
bpatel@766 111 li.addStyle(HtmlStyle.blockList);
bpatel@766 112 if (serializableFieldsTree.isValid()) {
bpatel@766 113 if (!printedOverallAnchor) {
bpatel@766 114 li.addContent(writer.getMarkerAnchor("serializedForm"));
bpatel@766 115 printedOverallAnchor = true;
bpatel@766 116 }
bpatel@766 117 Content headingContent = new StringContent(heading);
bpatel@766 118 Content serialHeading = HtmlTree.HEADING(HtmlConstants.SERIALIZED_MEMBER_HEADING,
bpatel@766 119 headingContent);
bpatel@766 120 li.addContent(serialHeading);
bpatel@766 121 li.addContent(serializableFieldsTree);
bpatel@766 122 }
bpatel@766 123 return li;
bpatel@766 124 }
bpatel@766 125
bpatel@766 126 /**
bpatel@766 127 * Add the member header.
bpatel@766 128 *
jjg@1358 129 * @param fieldType the class document to be listed
jjg@1358 130 * @param fieldTypeStr the string for the field type to be documented
bpatel@766 131 * @param fieldDimensions the dimensions of the field string to be added
jjg@1358 132 * @param fieldName name of the field to be added
bpatel@766 133 * @param contentTree the content tree to which the member header will be added
bpatel@766 134 */
bpatel@766 135 public void addMemberHeader(ClassDoc fieldType, String fieldTypeStr,
bpatel@766 136 String fieldDimensions, String fieldName, Content contentTree) {
bpatel@766 137 Content nameContent = new RawHtml(fieldName);
bpatel@766 138 Content heading = HtmlTree.HEADING(HtmlConstants.MEMBER_HEADING, nameContent);
bpatel@766 139 contentTree.addContent(heading);
bpatel@766 140 Content pre = new HtmlTree(HtmlTag.PRE);
bpatel@766 141 if (fieldType == null) {
bpatel@766 142 pre.addContent(fieldTypeStr);
bpatel@766 143 } else {
bpatel@766 144 Content fieldContent = new RawHtml(writer.getLink(new LinkInfoImpl(
bpatel@766 145 LinkInfoImpl.CONTEXT_SERIAL_MEMBER, fieldType)));
bpatel@766 146 pre.addContent(fieldContent);
bpatel@766 147 }
bpatel@766 148 pre.addContent(fieldDimensions + " ");
bpatel@766 149 pre.addContent(fieldName);
bpatel@766 150 contentTree.addContent(pre);
bpatel@766 151 }
bpatel@766 152
bpatel@766 153 /**
bpatel@766 154 * Add the deprecated information for this member.
duke@1 155 *
duke@1 156 * @param field the field to document.
bpatel@766 157 * @param contentTree the tree to which the deprecated info will be added
duke@1 158 */
bpatel@766 159 public void addMemberDeprecatedInfo(FieldDoc field, Content contentTree) {
bpatel@766 160 addDeprecatedInfo(field, contentTree);
bpatel@766 161 }
bpatel@766 162
bpatel@766 163 /**
bpatel@766 164 * Add the description text for this member.
bpatel@766 165 *
bpatel@766 166 * @param field the field to document.
bpatel@766 167 * @param contentTree the tree to which the deprecated info will be added
bpatel@766 168 */
bpatel@766 169 public void addMemberDescription(FieldDoc field, Content contentTree) {
duke@1 170 if (field.inlineTags().length > 0) {
bpatel@766 171 writer.addInlineComment(field, contentTree);
duke@1 172 }
duke@1 173 Tag[] tags = field.tags("serial");
duke@1 174 if (tags.length > 0) {
bpatel@766 175 writer.addInlineComment(field, tags[0], contentTree);
duke@1 176 }
duke@1 177 }
duke@1 178
duke@1 179 /**
bpatel@766 180 * Add the description text for this member represented by the tag.
duke@1 181 *
bpatel@766 182 * @param serialFieldTag the field to document (represented by tag)
bpatel@766 183 * @param contentTree the tree to which the deprecated info will be added
duke@1 184 */
bpatel@766 185 public void addMemberDescription(SerialFieldTag serialFieldTag, Content contentTree) {
bpatel@233 186 String serialFieldTagDesc = serialFieldTag.description().trim();
bpatel@233 187 if (!serialFieldTagDesc.isEmpty()) {
bpatel@766 188 Content serialFieldContent = new RawHtml(serialFieldTagDesc);
bpatel@766 189 Content div = HtmlTree.DIV(HtmlStyle.block, serialFieldContent);
bpatel@766 190 contentTree.addContent(div);
bpatel@233 191 }
duke@1 192 }
duke@1 193
duke@1 194 /**
bpatel@766 195 * Add the tag information for this member.
duke@1 196 *
duke@1 197 * @param field the field to document.
bpatel@766 198 * @param contentTree the tree to which the member tags info will be added
duke@1 199 */
bpatel@766 200 public void addMemberTags(FieldDoc field, Content contentTree) {
duke@1 201 TagletOutputImpl output = new TagletOutputImpl("");
duke@1 202 TagletWriter.genTagOuput(configuration().tagletManager, field,
bpatel@766 203 configuration().tagletManager.getCustomTags(field),
duke@1 204 writer.getTagletWriterInstance(false), output);
bpatel@233 205 String outputString = output.toString().trim();
bpatel@766 206 Content dlTags = new HtmlTree(HtmlTag.DL);
bpatel@233 207 if (!outputString.isEmpty()) {
bpatel@766 208 Content tagContent = new RawHtml(outputString);
bpatel@766 209 dlTags.addContent(tagContent);
duke@1 210 }
bpatel@766 211 contentTree.addContent(dlTags);
duke@1 212 }
bpatel@222 213
bpatel@222 214 /**
bpatel@233 215 * Check to see if overview details should be printed. If
bpatel@222 216 * nocomment option set or if there is no text to be printed
bpatel@233 217 * for deprecation info, comment or tags, do not print overview details.
bpatel@233 218 *
bpatel@233 219 * @param field the field to check overview details for.
bpatel@233 220 * @return true if overview details need to be printed
bpatel@222 221 */
bpatel@233 222 public boolean shouldPrintOverview(FieldDoc field) {
bpatel@233 223 if (!configuration().nocomment) {
bpatel@233 224 if(!field.commentText().isEmpty() ||
bpatel@233 225 writer.hasSerializationOverviewTags(field))
bpatel@222 226 return true;
bpatel@233 227 }
bpatel@233 228 if (field.tags("deprecated").length > 0)
bpatel@222 229 return true;
bpatel@222 230 return false;
bpatel@222 231 }
duke@1 232 }

mercurial