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