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 public class FieldWriterImpl extends AbstractMemberWriter 55 implements FieldWriter, MemberSummaryWriter { 56 57 public FieldWriterImpl(SubWriterHolderWriter writer, TypeElement typeElement) { 58 super(writer, typeElement); 59 } 60 61 public FieldWriterImpl(SubWriterHolderWriter writer) { 62 super(writer); 63 } 64 65 /** 66 * {@inheritDoc} 67 */ 68 @Override 69 public Content getMemberSummaryHeader(TypeElement typeElement, 70 Content memberSummaryTree) { 71 memberSummaryTree.add(MarkerComments.START_OF_FIELD_SUMMARY); 72 Content memberTree = new ContentBuilder(); 73 writer.addSummaryHeader(this, memberTree); 74 return memberTree; 75 } 76 77 /** 78 * {@inheritDoc} 79 */ 80 @Override 81 public void addMemberTree(Content memberSummaryTree, Content memberTree) { 82 writer.addMemberTree(HtmlStyle.fieldSummary, 83 SectionName.FIELD_SUMMARY, memberSummaryTree, memberTree); 84 } 85 86 /** 87 * {@inheritDoc} 88 */ 89 @Override 90 public Content getFieldDetailsTreeHeader(Content memberDetailsTree) { 91 memberDetailsTree.add(MarkerComments.START_OF_FIELD_DETAILS); 92 Content fieldDetailsTree = new ContentBuilder(); 93 Content heading = HtmlTree.HEADING(Headings.TypeDeclaration.DETAILS_HEADING, 94 contents.fieldDetailsLabel); 95 fieldDetailsTree.add(heading); 96 return fieldDetailsTree; 97 } 98 99 /** 100 * {@inheritDoc} 101 */ 102 @Override 103 public Content getFieldDocTreeHeader(VariableElement field) { 104 Content fieldTree = new ContentBuilder(); 105 Content heading = new HtmlTree(Headings.TypeDeclaration.MEMBER_HEADING, 106 new StringContent(name(field))); 107 fieldTree.add(heading); 108 return HtmlTree.SECTION(HtmlStyle.detail, fieldTree).setId(name(field)); 109 } 110 111 /** 112 * {@inheritDoc} 113 */ 114 @Override 115 public Content getSignature(VariableElement field) { 116 return new MemberSignature(field) 117 .addType(utils.asInstantiatedFieldType(typeElement, field)) 118 .toContent(); 119 } 120 121 /** 122 * {@inheritDoc} 123 */ 124 @Override 125 public void addDeprecated(VariableElement field, Content fieldTree) { 126 addDeprecatedInfo(field, fieldTree); 127 } 128 129 /** 130 * {@inheritDoc} 131 */ 132 @Override 133 public void addComments(VariableElement field, Content fieldTree) { 134 if (!utils.getFullBody(field).isEmpty()) { 135 writer.addInlineComment(field, fieldTree); 136 } 137 } 138 139 /** 140 * {@inheritDoc} 141 */ 142 @Override 143 public void addTags(VariableElement field, Content fieldTree) { 144 writer.addTagsInfo(field, fieldTree); 145 } 146 147 /** 148 * {@inheritDoc} 149 */ 150 @Override 151 public Content getFieldDetails(Content fieldDetailsTreeHeader, Content fieldDetailsTree) { 152 Content fieldDetails = new ContentBuilder(fieldDetailsTreeHeader, fieldDetailsTree); 153 return getMemberTree(HtmlTree.SECTION(HtmlStyle.fieldDetails, fieldDetails) 154 .setId(SectionName.FIELD_DETAIL.getName())); 155 } 156 157 /** 158 * {@inheritDoc} 159 */ 160 @Override 161 public Content getFieldDoc(Content fieldTree) { 162 return getMemberTree(fieldTree); 163 } 164 165 /** 166 * {@inheritDoc} 167 */ 168 @Override 169 public void addSummaryLabel(Content memberTree) { 170 Content label = HtmlTree.HEADING(Headings.TypeDeclaration.SUMMARY_HEADING, 171 contents.fieldSummaryLabel); 172 memberTree.add(label); 173 } 174 175 /** 176 * {@inheritDoc} 177 */ 178 @Override 179 public TableHeader getSummaryTableHeader(Element member) { 180 return new TableHeader(contents.modifierAndTypeLabel, contents.fieldLabel, 181 contents.descriptionLabel); 182 } 183 184 @Override 185 protected Table createSummaryTable() { 186 List<HtmlStyle> bodyRowStyles = Arrays.asList(HtmlStyle.colFirst, HtmlStyle.colSecond, 187 HtmlStyle.colLast); 188 189 return new Table(HtmlStyle.memberSummary) 190 .setCaption(contents.fields) 191 .setHeader(getSummaryTableHeader(typeElement)) 192 .setRowScopeColumn(1) 193 .setColumnStyles(bodyRowStyles); 194 } 195 196 /** 197 * {@inheritDoc} 198 */ 199 @Override 200 public void addInheritedSummaryLabel(TypeElement typeElement, Content inheritedTree) { 201 Content classLink = writer.getPreQualifiedClassLink( 202 LinkInfoImpl.Kind.MEMBER, typeElement, false); 203 Content label; 204 if (configuration.summarizeOverriddenMethods) { 205 label = new StringContent(utils.isClass(typeElement) 206 ? resources.getText("doclet.Fields_Declared_In_Class") 207 : resources.getText("doclet.Fields_Declared_In_Interface")); 208 } else { 209 label = new StringContent(utils.isClass(typeElement) 210 ? resources.getText("doclet.Fields_Inherited_From_Class") 211 : resources.getText("doclet.Fields_Inherited_From_Interface")); 212 } 213 HtmlTree labelHeading = HtmlTree.HEADING(Headings.TypeDeclaration.INHERITED_SUMMARY_HEADING, 214 label); 215 labelHeading.setId(SectionName.FIELDS_INHERITANCE.getName() 216 + links.getName(configuration.getClassName(typeElement))); 217 labelHeading.add(Entity.NO_BREAK_SPACE); 218 labelHeading.add(classLink); 219 inheritedTree.add(labelHeading); 220 } 221 222 /** 223 * {@inheritDoc} 224 */ 225 @Override 226 protected void addSummaryLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element member, 227 Content tdSummary) { 228 Content memberLink = HtmlTree.SPAN(HtmlStyle.memberNameLink, 229 writer.getDocLink(context, typeElement , member, name(member), false)); 230 Content code = HtmlTree.CODE(memberLink); 231 tdSummary.add(code); 232 } 233 234 /** 235 * {@inheritDoc} 236 */ 237 @Override 238 protected void addInheritedSummaryLink(TypeElement typeElement, Element member, Content linksTree) { 239 linksTree.add( 240 writer.getDocLink(LinkInfoImpl.Kind.MEMBER, typeElement, member, 241 name(member), false)); 242 } 243 244 /** 245 * {@inheritDoc} 246 */ 247 @Override 248 protected void addSummaryType(Element member, Content tdSummaryType) { 249 addModifierAndType(member, utils.asInstantiatedFieldType(typeElement, (VariableElement)member), tdSummaryType); 250 } 251 252 /** 253 * {@inheritDoc} 254 */ 255 @Override 256 protected Content getDeprecatedLink(Element member) { 257 String name = utils.getFullyQualifiedName(member) + "." + member.getSimpleName(); 258 return writer.getDocLink(LinkInfoImpl.Kind.MEMBER, member, name); 259 } 260 261 @Override 262 public Content getMemberTreeHeader(){ 263 return writer.getMemberTreeHeader(); 264 } 265 }