1 /* 2 * Copyright (c) 1997, 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.Arrays; 29 import java.util.List; 30 31 import javax.lang.model.element.Element; 32 import javax.lang.model.element.TypeElement; 33 import javax.lang.model.element.VariableElement; 34 35 import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder; 36 import jdk.javadoc.internal.doclets.formats.html.markup.Entity; 37 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; 38 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; 39 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; 40 import jdk.javadoc.internal.doclets.formats.html.markup.Table; 41 import jdk.javadoc.internal.doclets.formats.html.markup.TableHeader; 42 import jdk.javadoc.internal.doclets.toolkit.Content; 43 import jdk.javadoc.internal.doclets.toolkit.FieldWriter; 44 import jdk.javadoc.internal.doclets.toolkit.MemberSummaryWriter; 45 46 /** 47 * Writes field documentation in HTML format. 48 * 49 * <p><b>This is NOT part of any supported API. 50 * If you write code that depends on this, you do so at your own risk. 51 * This code and its internal interfaces are subject to change or 52 * deletion without notice.</b> 53 * 54 * @author Robert Field 55 * @author Atul M Dambalkar 56 * @author Jamie Ho (rewrite) 57 * @author Bhavesh Patel (Modified) 58 */ 59 public class FieldWriterImpl extends AbstractMemberWriter 60 implements FieldWriter, MemberSummaryWriter { 61 FieldWriterImpl(SubWriterHolderWriter writer, TypeElement typeElement)62 public FieldWriterImpl(SubWriterHolderWriter writer, TypeElement typeElement) { 63 super(writer, typeElement); 64 } 65 FieldWriterImpl(SubWriterHolderWriter writer)66 public FieldWriterImpl(SubWriterHolderWriter writer) { 67 super(writer); 68 } 69 70 /** 71 * {@inheritDoc} 72 */ 73 @Override getMemberSummaryHeader(TypeElement typeElement, Content memberSummaryTree)74 public Content getMemberSummaryHeader(TypeElement typeElement, 75 Content memberSummaryTree) { 76 memberSummaryTree.add(MarkerComments.START_OF_FIELD_SUMMARY); 77 Content memberTree = new ContentBuilder(); 78 writer.addSummaryHeader(this, typeElement, memberTree); 79 return memberTree; 80 } 81 82 /** 83 * {@inheritDoc} 84 */ 85 @Override addMemberTree(Content memberSummaryTree, Content memberTree)86 public void addMemberTree(Content memberSummaryTree, Content memberTree) { 87 writer.addMemberTree(HtmlStyle.fieldSummary, memberSummaryTree, memberTree); 88 } 89 90 /** 91 * {@inheritDoc} 92 */ 93 @Override getFieldDetailsTreeHeader(TypeElement typeElement, Content memberDetailsTree)94 public Content getFieldDetailsTreeHeader(TypeElement typeElement, Content memberDetailsTree) { 95 memberDetailsTree.add(MarkerComments.START_OF_FIELD_DETAILS); 96 Content fieldDetailsTree = new ContentBuilder(); 97 Content heading = HtmlTree.HEADING(Headings.TypeDeclaration.DETAILS_HEADING, 98 contents.fieldDetailsLabel); 99 fieldDetailsTree.add(links.createAnchor( 100 SectionName.FIELD_DETAIL)); 101 fieldDetailsTree.add(heading); 102 return fieldDetailsTree; 103 } 104 105 /** 106 * {@inheritDoc} 107 */ 108 @Override getFieldDocTreeHeader(VariableElement field, Content fieldDetailsTree)109 public Content getFieldDocTreeHeader(VariableElement field, Content fieldDetailsTree) { 110 Content fieldTree = new ContentBuilder(); 111 Content heading = new HtmlTree(Headings.TypeDeclaration.MEMBER_HEADING); 112 heading.add(links.createAnchor(name(field), new StringContent(name(field)))); 113 fieldTree.add(heading); 114 return HtmlTree.SECTION(HtmlStyle.detail, fieldTree); 115 } 116 117 /** 118 * {@inheritDoc} 119 */ 120 @Override getSignature(VariableElement field)121 public Content getSignature(VariableElement field) { 122 return new MemberSignature(field) 123 .addType(field.asType()) 124 .toContent(); 125 } 126 127 /** 128 * {@inheritDoc} 129 */ 130 @Override addDeprecated(VariableElement field, Content fieldTree)131 public void addDeprecated(VariableElement field, Content fieldTree) { 132 addDeprecatedInfo(field, fieldTree); 133 } 134 135 /** 136 * {@inheritDoc} 137 */ 138 @Override addComments(VariableElement field, Content fieldTree)139 public void addComments(VariableElement field, Content fieldTree) { 140 if (!utils.getFullBody(field).isEmpty()) { 141 writer.addInlineComment(field, fieldTree); 142 } 143 } 144 145 /** 146 * {@inheritDoc} 147 */ 148 @Override addTags(VariableElement field, Content fieldTree)149 public void addTags(VariableElement field, Content fieldTree) { 150 writer.addTagsInfo(field, fieldTree); 151 } 152 153 /** 154 * {@inheritDoc} 155 */ 156 @Override getFieldDetails(Content fieldDetailsTreeHeader, Content fieldDetailsTree)157 public Content getFieldDetails(Content fieldDetailsTreeHeader, Content fieldDetailsTree) { 158 Content fieldDetails = new ContentBuilder(fieldDetailsTreeHeader, fieldDetailsTree); 159 return getMemberTree(HtmlTree.SECTION(HtmlStyle.fieldDetails, fieldDetails)); 160 } 161 162 /** 163 * {@inheritDoc} 164 */ 165 @Override getFieldDoc(Content fieldTree)166 public Content getFieldDoc(Content fieldTree) { 167 return getMemberTree(fieldTree); 168 } 169 170 /** 171 * {@inheritDoc} 172 */ 173 @Override addSummaryLabel(Content memberTree)174 public void addSummaryLabel(Content memberTree) { 175 Content label = HtmlTree.HEADING(Headings.TypeDeclaration.SUMMARY_HEADING, 176 contents.fieldSummaryLabel); 177 memberTree.add(label); 178 } 179 180 /** 181 * {@inheritDoc} 182 */ 183 @Override getSummaryTableHeader(Element member)184 public TableHeader getSummaryTableHeader(Element member) { 185 return new TableHeader(contents.modifierAndTypeLabel, contents.fieldLabel, 186 contents.descriptionLabel); 187 } 188 189 @Override createSummaryTable()190 protected Table createSummaryTable() { 191 List<HtmlStyle> bodyRowStyles = Arrays.asList(HtmlStyle.colFirst, HtmlStyle.colSecond, 192 HtmlStyle.colLast); 193 194 return new Table(HtmlStyle.memberSummary) 195 .setCaption(contents.fields) 196 .setHeader(getSummaryTableHeader(typeElement)) 197 .setRowScopeColumn(1) 198 .setColumnStyles(bodyRowStyles); 199 } 200 201 /** 202 * {@inheritDoc} 203 */ 204 @Override addSummaryAnchor(TypeElement typeElement, Content memberTree)205 public void addSummaryAnchor(TypeElement typeElement, Content memberTree) { 206 memberTree.add(links.createAnchor( 207 SectionName.FIELD_SUMMARY)); 208 } 209 210 /** 211 * {@inheritDoc} 212 */ 213 @Override addInheritedSummaryAnchor(TypeElement typeElement, Content inheritedTree)214 public void addInheritedSummaryAnchor(TypeElement typeElement, Content inheritedTree) { 215 inheritedTree.add(links.createAnchor( 216 SectionName.FIELDS_INHERITANCE, configuration.getClassName(typeElement))); 217 } 218 219 /** 220 * {@inheritDoc} 221 */ 222 @Override addInheritedSummaryLabel(TypeElement typeElement, Content inheritedTree)223 public void addInheritedSummaryLabel(TypeElement typeElement, Content inheritedTree) { 224 Content classLink = writer.getPreQualifiedClassLink( 225 LinkInfoImpl.Kind.MEMBER, typeElement, false); 226 Content label; 227 if (configuration.summarizeOverriddenMethods) { 228 label = new StringContent(utils.isClass(typeElement) 229 ? resources.getText("doclet.Fields_Declared_In_Class") 230 : resources.getText("doclet.Fields_Declared_In_Interface")); 231 } else { 232 label = new StringContent(utils.isClass(typeElement) 233 ? resources.getText("doclet.Fields_Inherited_From_Class") 234 : resources.getText("doclet.Fields_Inherited_From_Interface")); 235 } 236 Content labelHeading = HtmlTree.HEADING(Headings.TypeDeclaration.INHERITED_SUMMARY_HEADING, 237 label); 238 labelHeading.add(Entity.NO_BREAK_SPACE); 239 labelHeading.add(classLink); 240 inheritedTree.add(labelHeading); 241 } 242 243 /** 244 * {@inheritDoc} 245 */ 246 @Override addSummaryLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element member, Content tdSummary)247 protected void addSummaryLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element member, 248 Content tdSummary) { 249 Content memberLink = HtmlTree.SPAN(HtmlStyle.memberNameLink, 250 writer.getDocLink(context, typeElement , member, name(member), false)); 251 Content code = HtmlTree.CODE(memberLink); 252 tdSummary.add(code); 253 } 254 255 /** 256 * {@inheritDoc} 257 */ 258 @Override addInheritedSummaryLink(TypeElement typeElement, Element member, Content linksTree)259 protected void addInheritedSummaryLink(TypeElement typeElement, Element member, Content linksTree) { 260 linksTree.add( 261 writer.getDocLink(LinkInfoImpl.Kind.MEMBER, typeElement, member, 262 name(member), false)); 263 } 264 265 /** 266 * {@inheritDoc} 267 */ 268 @Override addSummaryType(Element member, Content tdSummaryType)269 protected void addSummaryType(Element member, Content tdSummaryType) { 270 addModifierAndType(member, member.asType(), tdSummaryType); 271 } 272 273 /** 274 * {@inheritDoc} 275 */ 276 @Override getDeprecatedLink(Element member)277 protected Content getDeprecatedLink(Element member) { 278 String name = utils.getFullyQualifiedName(member) + "." + member.getSimpleName(); 279 return writer.getDocLink(LinkInfoImpl.Kind.MEMBER, member, name); 280 } 281 282 @Override getMemberTreeHeader()283 public Content getMemberTreeHeader(){ 284 return writer.getMemberTreeHeader(); 285 } 286 } 287