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 = new StringContent(
273 utils.isClass(typeElement)
274 ? configuration.getText("doclet.Properties_Inherited_From_Class")
275 : configuration.getText("doclet.Properties_Inherited_From_Interface"));
276 Content labelHeading = HtmlTree.HEADING(HtmlConstants.INHERITED_SUMMARY_HEADING,
277 label);
278 labelHeading.addContent(Contents.SPACE);
279 labelHeading.addContent(classLink);
280 inheritedTree.addContent(labelHeading);
281 }
282
283 /**
284 * {@inheritDoc}
285 */
286 @Override
287 protected void addSummaryLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element member,
288 Content tdSummary) {
289 Content memberLink = HtmlTree.SPAN(HtmlStyle.memberNameLink,
290 writer.getDocLink(context, typeElement,
291 member,
292 utils.getPropertyLabel(name(member)),
293 false,
294 true));
295
296 Content code = HtmlTree.CODE(memberLink);
297 tdSummary.addContent(code);
298 }
299
300 /**
301 * {@inheritDoc}
302 */
303 @Override
304 protected void addInheritedSummaryLink(TypeElement typeElement, Element member, Content linksTree) {
305 String mname = name(member);
306 Content content = writer.getDocLink(LinkInfoImpl.Kind.MEMBER, typeElement, member,
307 utils.isProperty(mname) ? utils.getPropertyName(mname) : mname,
308 false, true);
309 linksTree.addContent(content);
310 }
311
312 /**
313 * {@inheritDoc}
314 */
315 @Override
316 protected void addSummaryType(Element member, Content tdSummaryType) {
317 addModifierAndType(member, utils.getReturnType((ExecutableElement)member), tdSummaryType);
318 }
319
320 /**
321 * {@inheritDoc}
322 */
323 @Override
324 protected Content getDeprecatedLink(Element member) {
325 return writer.getDocLink(LinkInfoImpl.Kind.MEMBER, member,
326 utils.getFullyQualifiedName(member));
327 }
328
329 /**
330 * {@inheritDoc}
331 */
332 @Override
333 protected Content getNavSummaryLink(TypeElement typeElement, boolean link) {
334 if (link) {
335 if (typeElement == null) {
336 return writer.getHyperLink(
337 SectionName.PROPERTY_SUMMARY,
338 contents.navProperty);
339 } else {
340 return writer.getHyperLink(
341 SectionName.PROPERTIES_INHERITANCE,
342 configuration.getClassName(typeElement), contents.navProperty);
343 }
344 } else {
345 return contents.navProperty;
346 }
347 }
348
349 /**
350 * {@inheritDoc}
351 */
352 @Override
353 protected void addNavDetailLink(boolean link, Content liNav) {
354 if (link) {
355 liNav.addContent(writer.getHyperLink(
356 SectionName.PROPERTY_DETAIL,
357 contents.navProperty));
358 } else {
359 liNav.addContent(contents.navProperty);
360 }
361 }
362 }