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