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