1 /* 2 * Copyright (c) 1997, 2017, 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.ExecutableElement; 33 import javax.lang.model.element.TypeElement; 34 35 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants; 36 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; 37 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag; 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.toolkit.Content; 41 import jdk.javadoc.internal.doclets.toolkit.MemberSummaryWriter; 42 import jdk.javadoc.internal.doclets.toolkit.PropertyWriter; 43 44 45 /** 46 * Writes property documentation in HTML format. 47 * 48 * <p><b>This is NOT part of any supported API. 49 * If you write code that depends on this, you do so at your own risk. 50 * This code and its internal interfaces are subject to change or 51 * deletion without notice.</b> 52 * 53 * @author Robert Field 54 * @author Atul M Dambalkar 55 * @author Jamie Ho (rewrite) 56 * @author Bhavesh Patel (Modified) 57 */ 58 public class PropertyWriterImpl extends AbstractMemberWriter 59 implements PropertyWriter, MemberSummaryWriter { 60 61 public PropertyWriterImpl(SubWriterHolderWriter writer, TypeElement typeElement) { 62 super(writer, typeElement); 63 } 64 65 /** 66 * {@inheritDoc} 67 */ 68 @Override 69 public Content getMemberSummaryHeader(TypeElement typeElement, 70 Content memberSummaryTree) { 71 memberSummaryTree.addContent(HtmlConstants.START_OF_PROPERTY_SUMMARY); 72 Content memberTree = writer.getMemberTreeHeader(); 73 writer.addSummaryHeader(this, typeElement, memberTree); 74 return memberTree; 75 } 76 77 @Override 78 public boolean showTabs() { 79 return false; 80 } 81 82 /** 83 * {@inheritDoc} 84 */ 85 public void addMemberTree(Content memberSummaryTree, Content memberTree) { 86 writer.addMemberTree(memberSummaryTree, memberTree); 87 } 88 89 /** 90 * {@inheritDoc} 91 */ 92 @Override 93 public Content getPropertyDetailsTreeHeader(TypeElement typeElement, 94 Content memberDetailsTree) { 95 memberDetailsTree.addContent(HtmlConstants.START_OF_PROPERTY_DETAILS); 96 Content propertyDetailsTree = writer.getMemberTreeHeader(); 97 propertyDetailsTree.addContent(writer.getMarkerAnchor( 98 SectionName.PROPERTY_DETAIL)); 99 Content heading = HtmlTree.HEADING(HtmlConstants.DETAILS_HEADING, 100 contents.propertyDetailsLabel); 101 propertyDetailsTree.addContent(heading); 102 return propertyDetailsTree; 103 } 104 105 /** 106 * {@inheritDoc} 107 */ 108 @Override 109 public Content getPropertyDocTreeHeader(ExecutableElement property, 110 Content propertyDetailsTree) { 111 propertyDetailsTree.addContent( 112 writer.getMarkerAnchor(name(property))); 113 Content propertyDocTree = writer.getMemberTreeHeader(); 114 Content heading = new HtmlTree(HtmlConstants.MEMBER_HEADING); 115 heading.addContent(utils.getPropertyLabel(name(property))); 116 propertyDocTree.addContent(heading); 117 return propertyDocTree; 118 } 119 120 /** 121 * {@inheritDoc} 122 */ 123 @Override 124 public Content getSignature(ExecutableElement property) { 125 Content pre = new HtmlTree(HtmlTag.PRE); 126 writer.addAnnotationInfo(property, pre); 127 addModifiers(property, pre); 128 Content propertylink = writer.getLink(new LinkInfoImpl( 129 configuration, LinkInfoImpl.Kind.MEMBER, 130 utils.getReturnType(property))); 131 pre.addContent(propertylink); 132 pre.addContent(" "); 133 if (configuration.linksource) { 134 Content propertyName = new StringContent(name(property)); 135 writer.addSrcLink(property, propertyName, pre); 136 } else { 137 addName(name(property), pre); 138 } 139 return pre; 140 } 141 142 /** 143 * {@inheritDoc} 144 */ 145 @Override 146 public void addDeprecated(ExecutableElement property, Content propertyDocTree) { 147 } 148 149 /** 150 * {@inheritDoc} 151 */ 152 @Override 153 public void addComments(ExecutableElement property, Content propertyDocTree) { 154 TypeElement holder = (TypeElement)property.getEnclosingElement(); 155 if (!utils.getFullBody(property).isEmpty()) { 156 if (holder.equals(typeElement) || 157 (!utils.isPublic(holder) || utils.isLinkable(holder))) { 158 writer.addInlineComment(property, propertyDocTree); 159 } else { 160 Content link = 161 writer.getDocLink(LinkInfoImpl.Kind.PROPERTY_COPY, 162 holder, property, 163 utils.isIncluded(holder) 164 ? holder.getSimpleName() : holder.getQualifiedName(), 165 false); 166 Content codeLink = HtmlTree.CODE(link); 167 Content descfrmLabel = HtmlTree.SPAN(HtmlStyle.descfrmTypeLabel, 168 utils.isClass(holder) 169 ? contents.descfrmClassLabel 170 : contents.descfrmInterfaceLabel); 171 descfrmLabel.addContent(Contents.SPACE); 172 descfrmLabel.addContent(codeLink); 173 propertyDocTree.addContent(HtmlTree.DIV(HtmlStyle.block, descfrmLabel)); 174 writer.addInlineComment(property, propertyDocTree); 175 } 176 } 177 } 178 179 /** 180 * {@inheritDoc} 181 */ 182 @Override 183 public void addTags(ExecutableElement property, Content propertyDocTree) { 184 writer.addTagsInfo(property, propertyDocTree); 185 } 186 187 /** 188 * {@inheritDoc} 189 */ 190 @Override 191 public Content getPropertyDetails(Content propertyDetailsTree) { 192 if (configuration.allowTag(HtmlTag.SECTION)) { 193 HtmlTree htmlTree = HtmlTree.SECTION(getMemberTree(propertyDetailsTree)); 194 return htmlTree; 195 } 196 return getMemberTree(propertyDetailsTree); 197 } 198 199 /** 200 * {@inheritDoc} 201 */ 202 @Override 203 public Content getPropertyDoc(Content propertyDocTree, 204 boolean isLastContent) { 205 return getMemberTree(propertyDocTree, isLastContent); 206 } 207 208 /** 209 * {@inheritDoc} 210 */ 211 @Override 212 public void addSummaryLabel(Content memberTree) { 213 Content label = HtmlTree.HEADING(HtmlConstants.SUMMARY_HEADING, 214 contents.propertySummary); 215 memberTree.addContent(label); 216 } 217 218 /** 219 * {@inheritDoc} 220 */ 221 @Override 222 public String getTableSummary() { 223 return resources.getText("doclet.Member_Table_Summary", 224 resources.getText("doclet.Property_Summary"), 225 resources.getText("doclet.properties")); 226 } 227 228 /** 229 * {@inheritDoc} 230 */ 231 @Override 232 public Content getCaption() { 233 return contents.properties; 234 } 235 236 /** 237 * {@inheritDoc} 238 */ 239 @Override 240 public List<String> getSummaryTableHeader(Element member) { 241 List<String> header = Arrays.asList(resources.getText("doclet.Type"), 242 resources.getText("doclet.Property"), resources.getText("doclet.Description")); 243 return header; 244 } 245 246 /** 247 * {@inheritDoc} 248 */ 249 @Override 250 public void addSummaryAnchor(TypeElement typeElement, Content memberTree) { 251 memberTree.addContent(writer.getMarkerAnchor( 252 SectionName.PROPERTY_SUMMARY)); 253 } 254 255 /** 256 * {@inheritDoc} 257 */ 258 @Override 259 public void addInheritedSummaryAnchor(TypeElement typeElement, Content inheritedTree) { 260 inheritedTree.addContent(writer.getMarkerAnchor( 261 SectionName.PROPERTIES_INHERITANCE, 262 configuration.getClassName(typeElement))); 263 } 264 265 /** 266 * {@inheritDoc} 267 */ 268 @Override 269 public void addInheritedSummaryLabel(TypeElement typeElement, Content inheritedTree) { 270 Content classLink = writer.getPreQualifiedClassLink( 271 LinkInfoImpl.Kind.MEMBER, typeElement, false); 272 Content label; 273 if (configuration.summarizeOverriddenMethods) { 274 label = new StringContent(utils.isClass(typeElement) 275 ? configuration.getText("doclet.Properties_Declared_In_Class") 276 : configuration.getText("doclet.Properties_Declared_In_Interface")); 277 } else { 278 label = new StringContent(utils.isClass(typeElement) 279 ? configuration.getText("doclet.Properties_Inherited_From_Class") 280 : configuration.getText("doclet.Properties_Inherited_From_Interface")); 281 } 282 Content labelHeading = HtmlTree.HEADING(HtmlConstants.INHERITED_SUMMARY_HEADING, 283 label); 284 labelHeading.addContent(Contents.SPACE); 285 labelHeading.addContent(classLink); 286 inheritedTree.addContent(labelHeading); 287 } 288 289 /** 290 * {@inheritDoc} 291 */ 292 @Override 293 protected void addSummaryLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element member, 294 Content tdSummary) { 295 Content memberLink = HtmlTree.SPAN(HtmlStyle.memberNameLink, 296 writer.getDocLink(context, typeElement, 297 member, 298 utils.getPropertyLabel(name(member)), 299 false, 300 true)); 301 302 Content code = HtmlTree.CODE(memberLink); 303 tdSummary.addContent(code); 304 } 305 306 /** 307 * {@inheritDoc} 308 */ 309 @Override 310 protected void addInheritedSummaryLink(TypeElement typeElement, Element member, Content linksTree) { 311 String mname = name(member); 312 Content content = writer.getDocLink(LinkInfoImpl.Kind.MEMBER, typeElement, member, 313 utils.isProperty(mname) ? utils.getPropertyName(mname) : mname, 314 false, true); 315 linksTree.addContent(content); 316 } 317 318 /** 319 * {@inheritDoc} 320 */ 321 @Override 322 protected void addSummaryType(Element member, Content tdSummaryType) { 323 addModifierAndType(member, utils.getReturnType((ExecutableElement)member), tdSummaryType); 324 } 325 326 /** 327 * {@inheritDoc} 328 */ 329 @Override 330 protected Content getDeprecatedLink(Element member) { 331 return writer.getDocLink(LinkInfoImpl.Kind.MEMBER, member, 332 utils.getFullyQualifiedName(member)); 333 } 334 335 /** 336 * {@inheritDoc} 337 */ 338 @Override 339 protected Content getNavSummaryLink(TypeElement typeElement, boolean link) { 340 if (link) { 341 if (typeElement == null) { 342 return writer.getHyperLink( 343 SectionName.PROPERTY_SUMMARY, 344 contents.navProperty); 345 } else { 346 return writer.getHyperLink( 347 SectionName.PROPERTIES_INHERITANCE, 348 configuration.getClassName(typeElement), contents.navProperty); 349 } 350 } else { 351 return contents.navProperty; 352 } 353 } 354 355 /** 356 * {@inheritDoc} 357 */ 358 @Override 359 protected void addNavDetailLink(boolean link, Content liNav) { 360 if (link) { 361 liNav.addContent(writer.getHyperLink( 362 SectionName.PROPERTY_DETAIL, 363 contents.navProperty)); 364 } else { 365 liNav.addContent(contents.navProperty); 366 } 367 } 368 }