1 /*
   2  * Copyright (c) 1998, 2019, 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.formats.html;
  27 
  28 import java.util.*;
  29 
  30 import javax.lang.model.element.TypeElement;
  31 import javax.lang.model.element.VariableElement;
  32 import javax.lang.model.type.TypeMirror;
  33 
  34 import com.sun.source.doctree.DocTree;
  35 
  36 import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
  37 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
  38 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
  39 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
  40 import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;
  41 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
  42 import jdk.javadoc.internal.doclets.toolkit.Content;
  43 import jdk.javadoc.internal.doclets.toolkit.SerializedFormWriter;
  44 import jdk.javadoc.internal.doclets.toolkit.taglets.TagletWriter;
  45 import 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  */
  60 public 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.setStyle(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         li.setStyle(HtmlStyle.blockList);
  91         return li;
  92     }
  93 
  94     /**
  95      * Add serializable fields.
  96      *
  97      * @param heading the heading for the section
  98      * @param serializableFieldsTree the tree to be added to the serializable fileds
  99      *        content tree
 100      * @return a content tree for the serializable fields content
 101      */
 102     public Content getSerializableFields(String heading, Content serializableFieldsTree) {
 103         HtmlTree section = HtmlTree.SECTION(HtmlStyle.detail);
 104         if (serializableFieldsTree.isValid()) {
 105             Content headingContent = new StringContent(heading);
 106             Content serialHeading = HtmlTree.HEADING(Headings.SerializedForm.CLASS_SUBHEADING, headingContent);
 107             section.add(serialHeading);
 108             section.add(serializableFieldsTree);
 109         }
 110         return HtmlTree.LI(HtmlStyle.blockList, section);
 111     }
 112 
 113     @Override
 114     public void addMemberHeader(TypeElement fieldType, String fieldTypeStr,
 115             String fieldDimensions, String fieldName, Content contentTree) {
 116         Content nameContent = new StringContent(fieldName);
 117         Content heading = HtmlTree.HEADING(Headings.SerializedForm.MEMBER_HEADING, nameContent);
 118         contentTree.add(heading);
 119         Content pre = new HtmlTree(HtmlTag.PRE);
 120         if (fieldType == null) {
 121             pre.add(fieldTypeStr);
 122         } else {
 123             Content fieldContent = writer.getLink(new LinkInfoImpl(
 124                     configuration, LinkInfoImpl.Kind.SERIAL_MEMBER, fieldType));
 125             pre.add(fieldContent);
 126         }
 127         pre.add(fieldDimensions + " ");
 128         pre.add(fieldName);
 129         contentTree.add(pre);
 130     }
 131 
 132     @Override
 133     public void addMemberHeader(TypeMirror fieldType, String fieldName, Content contentTree) {
 134         Content nameContent = new StringContent(fieldName);
 135         Content heading = HtmlTree.HEADING(HtmlTag.H5, nameContent);
 136         contentTree.add(heading);
 137         Content pre = new HtmlTree(HtmlTag.PRE);
 138         Content fieldContent = writer.getLink(new LinkInfoImpl(
 139                 configuration, LinkInfoImpl.Kind.SERIAL_MEMBER, fieldType));
 140         pre.add(fieldContent);
 141         pre.add(" ");
 142         pre.add(fieldName);
 143         contentTree.add(pre);
 144     }
 145 
 146     /**
 147      * Add the deprecated information for this member.
 148      *
 149      * @param field the field to document.
 150      * @param contentTree the tree to which the deprecated info will be added
 151      */
 152     public void addMemberDeprecatedInfo(VariableElement field, Content contentTree) {
 153         addDeprecatedInfo(field, contentTree);
 154     }
 155 
 156     /**
 157      * Add the description text for this member.
 158      *
 159      * @param field the field to document.
 160      * @param contentTree the tree to which the deprecated info will be added
 161      */
 162     public void addMemberDescription(VariableElement field, Content contentTree) {
 163         if (!utils.getFullBody(field).isEmpty()) {
 164             writer.addInlineComment(field, contentTree);
 165         }
 166         List<? extends DocTree> tags = utils.getBlockTags(field, DocTree.Kind.SERIAL);
 167         if (!tags.isEmpty()) {
 168             writer.addInlineComment(field, tags.get(0), contentTree);
 169         }
 170     }
 171 
 172     /**
 173      * Add the description text for this member represented by the tag.
 174      *
 175      * @param serialFieldTag the field to document (represented by tag)
 176      * @param contentTree the tree to which the deprecated info will be added
 177      */
 178     public void addMemberDescription(VariableElement field, DocTree serialFieldTag, Content contentTree) {
 179         CommentHelper ch = utils.getCommentHelper(field);
 180         List<? extends DocTree> description = ch.getDescription(configuration, serialFieldTag);
 181         if (!description.isEmpty()) {
 182             Content serialFieldContent = new RawHtml(ch.getText(description));
 183             Content div = HtmlTree.DIV(HtmlStyle.block, serialFieldContent);
 184             contentTree.add(div);
 185         }
 186     }
 187 
 188     /**
 189      * Add the tag information for this member.
 190      *
 191      * @param field the field to document.
 192      * @param contentTree the tree to which the member tags info will be added
 193      */
 194     public void addMemberTags(VariableElement field, Content contentTree) {
 195         Content tagContent = new ContentBuilder();
 196         TagletWriter.genTagOutput(configuration.tagletManager, field,
 197                 configuration.tagletManager.getBlockTaglets(field),
 198                 writer.getTagletWriterInstance(false), tagContent);
 199         Content dlTags = new HtmlTree(HtmlTag.DL);
 200         dlTags.add(tagContent);
 201         contentTree.add(dlTags);  // TODO: what if empty?
 202     }
 203 
 204     /**
 205      * Check to see if overview details should be printed. If
 206      * nocomment option set or if there is no text to be printed
 207      * for deprecation info, comment or tags, do not print overview details.
 208      *
 209      * @param field the field to check overview details for.
 210      * @return true if overview details need to be printed
 211      */
 212     public boolean shouldPrintOverview(VariableElement field) {
 213         if (!configuration.nocomment) {
 214             if(!utils.getFullBody(field).isEmpty() ||
 215                     writer.hasSerializationOverviewTags(field))
 216                 return true;
 217         }
 218         if (utils.isDeprecated(field))
 219             return true;
 220         return false;
 221     }
 222 }