View Javadoc
1   /*
2    * Copyright (c) 1997, 2013, 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 com.sun.tools.doclets.formats.html;
27  
28  import java.io.*;
29  import java.util.*;
30  
31  import com.sun.javadoc.*;
32  import com.sun.tools.doclets.formats.html.markup.*;
33  import com.sun.tools.doclets.internal.toolkit.*;
34  import com.sun.tools.doclets.internal.toolkit.util.*;
35  
36  /**
37   * Writes constructor documentation.
38   *
39   *  <p><b>This is NOT part of any supported API.
40   *  If you write code that depends on this, you do so at your own risk.
41   *  This code and its internal interfaces are subject to change or
42   *  deletion without notice.</b>
43   *
44   * @author Robert Field
45   * @author Atul M Dambalkar
46   * @author Bhavesh Patel (Modified)
47   */
48  public class ConstructorWriterImpl extends AbstractExecutableMemberWriter
49      implements ConstructorWriter, MemberSummaryWriter {
50  
51      private boolean foundNonPubConstructor = false;
52  
53      /**
54       * Construct a new ConstructorWriterImpl.
55       *
56       * @param writer The writer for the class that the constructors belong to.
57       * @param classDoc the class being documented.
58       */
59      public ConstructorWriterImpl(SubWriterHolderWriter writer,
60              ClassDoc classDoc) {
61          super(writer, classDoc);
62          VisibleMemberMap visibleMemberMap = new VisibleMemberMap(classDoc,
63              VisibleMemberMap.CONSTRUCTORS, configuration);
64          List<ProgramElementDoc> constructors = new ArrayList<ProgramElementDoc>(visibleMemberMap.getMembersFor(classDoc));
65          for (int i = 0; i < constructors.size(); i++) {
66              if ((constructors.get(i)).isProtected() ||
67                  (constructors.get(i)).isPrivate()) {
68                  setFoundNonPubConstructor(true);
69              }
70          }
71      }
72  
73      /**
74       * Construct a new ConstructorWriterImpl.
75       *
76       * @param writer The writer for the class that the constructors belong to.
77       */
78      public ConstructorWriterImpl(SubWriterHolderWriter writer) {
79          super(writer);
80      }
81  
82      /**
83       * {@inheritDoc}
84       */
85      public Content getMemberSummaryHeader(ClassDoc classDoc,
86              Content memberSummaryTree) {
87          memberSummaryTree.addContent(HtmlConstants.START_OF_CONSTRUCTOR_SUMMARY);
88          Content memberTree = writer.getMemberTreeHeader();
89          writer.addSummaryHeader(this, classDoc, memberTree);
90          return memberTree;
91      }
92  
93      /**
94       * {@inheritDoc}
95       */
96      public Content getConstructorDetailsTreeHeader(ClassDoc classDoc,
97              Content memberDetailsTree) {
98          memberDetailsTree.addContent(HtmlConstants.START_OF_CONSTRUCTOR_DETAILS);
99          Content constructorDetailsTree = writer.getMemberTreeHeader();
100         constructorDetailsTree.addContent(writer.getMarkerAnchor(
101                 SectionName.CONSTRUCTOR_DETAIL));
102         Content heading = HtmlTree.HEADING(HtmlConstants.DETAILS_HEADING,
103                 writer.constructorDetailsLabel);
104         constructorDetailsTree.addContent(heading);
105         return constructorDetailsTree;
106     }
107 
108     /**
109      * {@inheritDoc}
110      */
111     public Content getConstructorDocTreeHeader(ConstructorDoc constructor,
112             Content constructorDetailsTree) {
113         String erasureAnchor;
114         if ((erasureAnchor = getErasureAnchor(constructor)) != null) {
115             constructorDetailsTree.addContent(writer.getMarkerAnchor((erasureAnchor)));
116         }
117         constructorDetailsTree.addContent(
118                 writer.getMarkerAnchor(writer.getAnchor(constructor)));
119         Content constructorDocTree = writer.getMemberTreeHeader();
120         Content heading = new HtmlTree(HtmlConstants.MEMBER_HEADING);
121         heading.addContent(constructor.name());
122         constructorDocTree.addContent(heading);
123         return constructorDocTree;
124     }
125 
126     /**
127      * {@inheritDoc}
128      */
129     public Content getSignature(ConstructorDoc constructor) {
130         Content pre = new HtmlTree(HtmlTag.PRE);
131         writer.addAnnotationInfo(constructor, pre);
132         addModifiers(constructor, pre);
133         if (configuration.linksource) {
134             Content constructorName = new StringContent(constructor.name());
135             writer.addSrcLink(constructor, constructorName, pre);
136         } else {
137             addName(constructor.name(), pre);
138         }
139         int indent = pre.charCount();
140         addParameters(constructor, pre, indent);
141         addExceptions(constructor, pre, indent);
142         return pre;
143     }
144 
145     /**
146      * {@inheritDoc}
147      */
148     @Override
149     public void setSummaryColumnStyle(HtmlTree tdTree) {
150         if (foundNonPubConstructor)
151             tdTree.addStyle(HtmlStyle.colLast);
152         else
153             tdTree.addStyle(HtmlStyle.colOne);
154     }
155 
156     /**
157      * {@inheritDoc}
158      */
159     public void addDeprecated(ConstructorDoc constructor, Content constructorDocTree) {
160         addDeprecatedInfo(constructor, constructorDocTree);
161     }
162 
163     /**
164      * {@inheritDoc}
165      */
166     public void addComments(ConstructorDoc constructor, Content constructorDocTree) {
167         addComment(constructor, constructorDocTree);
168     }
169 
170     /**
171      * {@inheritDoc}
172      */
173     public void addTags(ConstructorDoc constructor, Content constructorDocTree) {
174         writer.addTagsInfo(constructor, constructorDocTree);
175     }
176 
177     /**
178      * {@inheritDoc}
179      */
180     public Content getConstructorDetails(Content constructorDetailsTree) {
181         return getMemberTree(constructorDetailsTree);
182     }
183 
184     /**
185      * {@inheritDoc}
186      */
187     public Content getConstructorDoc(Content constructorDocTree,
188             boolean isLastContent) {
189         return getMemberTree(constructorDocTree, isLastContent);
190     }
191 
192     /**
193      * Close the writer.
194      */
195     public void close() throws IOException {
196         writer.close();
197     }
198 
199     /**
200      * Let the writer know whether a non public constructor was found.
201      *
202      * @param foundNonPubConstructor true if we found a non public constructor.
203      */
204     public void setFoundNonPubConstructor(boolean foundNonPubConstructor) {
205         this.foundNonPubConstructor = foundNonPubConstructor;
206     }
207 
208     /**
209      * {@inheritDoc}
210      */
211     public void addSummaryLabel(Content memberTree) {
212         Content label = HtmlTree.HEADING(HtmlConstants.SUMMARY_HEADING,
213                 writer.getResource("doclet.Constructor_Summary"));
214         memberTree.addContent(label);
215     }
216 
217     /**
218      * {@inheritDoc}
219      */
220     public String getTableSummary() {
221         return configuration.getText("doclet.Member_Table_Summary",
222                 configuration.getText("doclet.Constructor_Summary"),
223                 configuration.getText("doclet.constructors"));
224     }
225 
226     /**
227      * {@inheritDoc}
228      */
229     public Content getCaption() {
230         return configuration.getResource("doclet.Constructors");
231     }
232 
233     /**
234      * {@inheritDoc}
235      */
236     public String[] getSummaryTableHeader(ProgramElementDoc member) {
237         String[] header;
238         if (foundNonPubConstructor) {
239             header = new String[] {
240                 configuration.getText("doclet.Modifier"),
241                 configuration.getText("doclet.0_and_1",
242                         configuration.getText("doclet.Constructor"),
243                         configuration.getText("doclet.Description"))
244             };
245         }
246         else {
247             header = new String[] {
248                 configuration.getText("doclet.0_and_1",
249                         configuration.getText("doclet.Constructor"),
250                         configuration.getText("doclet.Description"))
251             };
252         }
253         return header;
254     }
255 
256     /**
257      * {@inheritDoc}
258      */
259     public void addSummaryAnchor(ClassDoc cd, Content memberTree) {
260         memberTree.addContent(writer.getMarkerAnchor(
261                 SectionName.CONSTRUCTOR_SUMMARY));
262     }
263 
264     /**
265      * {@inheritDoc}
266      */
267     public void addInheritedSummaryAnchor(ClassDoc cd, Content inheritedTree) {
268     }
269 
270     /**
271      * {@inheritDoc}
272      */
273     public void addInheritedSummaryLabel(ClassDoc cd, Content inheritedTree) {
274     }
275 
276     public int getMemberKind() {
277         return VisibleMemberMap.CONSTRUCTORS;
278     }
279 
280     /**
281      * {@inheritDoc}
282      */
283     protected Content getNavSummaryLink(ClassDoc cd, boolean link) {
284         if (link) {
285             return writer.getHyperLink(SectionName.CONSTRUCTOR_SUMMARY,
286                     writer.getResource("doclet.navConstructor"));
287         } else {
288             return writer.getResource("doclet.navConstructor");
289         }
290     }
291 
292     /**
293      * {@inheritDoc}
294      */
295     protected void addNavDetailLink(boolean link, Content liNav) {
296         if (link) {
297             liNav.addContent(writer.getHyperLink(
298                     SectionName.CONSTRUCTOR_DETAIL,
299                     writer.getResource("doclet.navConstructor")));
300         } else {
301             liNav.addContent(writer.getResource("doclet.navConstructor"));
302         }
303     }
304 
305     /**
306      * {@inheritDoc}
307      */
308     protected void addSummaryType(ProgramElementDoc member, Content tdSummaryType) {
309         if (foundNonPubConstructor) {
310             Content code = new HtmlTree(HtmlTag.CODE);
311             if (member.isProtected()) {
312                 code.addContent("protected ");
313             } else if (member.isPrivate()) {
314                 code.addContent("private ");
315             } else if (member.isPublic()) {
316                 code.addContent(writer.getSpace());
317             } else {
318                 code.addContent(
319                         configuration.getText("doclet.Package_private"));
320             }
321             tdSummaryType.addContent(code);
322         }
323     }
324 }