Sun, 24 Feb 2013 11:36:58 -0800
7112427: The doclet needs to be able to generate JavaFX documentation.
Reviewed-by: jjg
Contributed-by: jan.valenta@oracle.com
1 /*
2 * Copyright (c) 2003, 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 */
26 package com.sun.tools.doclets.internal.toolkit.builders;
28 import java.util.*;
30 import com.sun.javadoc.*;
31 import com.sun.tools.doclets.internal.toolkit.*;
32 import com.sun.tools.doclets.internal.toolkit.util.*;
34 /**
35 * Builds documentation for a method.
36 *
37 * <p><b>This is NOT part of any supported API.
38 * If you write code that depends on this, you do so at your own risk.
39 * This code and its internal interfaces are subject to change or
40 * deletion without notice.</b>
41 *
42 * @author Jamie Ho
43 * @author Bhavesh Patel (Modified)
44 * @since 1.5
45 */
46 public class MethodBuilder extends AbstractMemberBuilder {
48 /**
49 * The index of the current field that is being documented at this point
50 * in time.
51 */
52 private int currentMethodIndex;
54 /**
55 * The class whose methods are being documented.
56 */
57 private final ClassDoc classDoc;
59 /**
60 * The visible methods for the given class.
61 */
62 private final VisibleMemberMap visibleMemberMap;
64 /**
65 * The writer to output the method documentation.
66 */
67 private final MethodWriter writer;
69 /**
70 * The methods being documented.
71 */
72 private List<ProgramElementDoc> methods;
75 /**
76 * Construct a new MethodBuilder.
77 *
78 * @param context the build context.
79 * @param classDoc the class whoses members are being documented.
80 * @param writer the doclet specific writer.
81 */
82 private MethodBuilder(Context context,
83 ClassDoc classDoc,
84 MethodWriter writer) {
85 super(context);
86 this.classDoc = classDoc;
87 this.writer = writer;
88 visibleMemberMap = new VisibleMemberMap(
89 classDoc,
90 VisibleMemberMap.METHODS,
91 configuration);
92 methods =
93 new ArrayList<ProgramElementDoc>(visibleMemberMap.getLeafClassMembers(
94 configuration));
95 if (configuration.getMemberComparator() != null) {
96 Collections.sort(methods, configuration.getMemberComparator());
97 }
98 }
100 /**
101 * Construct a new MethodBuilder.
102 *
103 * @param context the build context.
104 * @param classDoc the class whoses members are being documented.
105 * @param writer the doclet specific writer.
106 *
107 * @return an instance of a MethodBuilder.
108 */
109 public static MethodBuilder getInstance(Context context,
110 ClassDoc classDoc, MethodWriter writer) {
111 return new MethodBuilder(context, classDoc, writer);
112 }
114 /**
115 * {@inheritDoc}
116 */
117 public String getName() {
118 return "MethodDetails";
119 }
121 /**
122 * Returns a list of methods that will be documented for the given class.
123 * This information can be used for doclet specific documentation
124 * generation.
125 *
126 * @param classDoc the {@link ClassDoc} we want to check.
127 * @return a list of methods that will be documented.
128 */
129 public List<ProgramElementDoc> members(ClassDoc classDoc) {
130 return visibleMemberMap.getMembersFor(classDoc);
131 }
133 /**
134 * Returns the visible member map for the methods of this class.
135 *
136 * @return the visible member map for the methods of this class.
137 */
138 public VisibleMemberMap getVisibleMemberMap() {
139 return visibleMemberMap;
140 }
142 /**
143 * {@inheritDoc}
144 */
145 public boolean hasMembersToDocument() {
146 return methods.size() > 0;
147 }
149 /**
150 * Build the method documentation.
151 *
152 * @param node the XML element that specifies which components to document
153 * @param memberDetailsTree the content tree to which the documentation will be added
154 */
155 public void buildMethodDoc(XMLNode node, Content memberDetailsTree) {
156 if (writer == null) {
157 return;
158 }
159 int size = methods.size();
160 if (size > 0) {
161 Content methodDetailsTree = writer.getMethodDetailsTreeHeader(
162 classDoc, memberDetailsTree);
163 for (currentMethodIndex = 0; currentMethodIndex < size;
164 currentMethodIndex++) {
165 Content methodDocTree = writer.getMethodDocTreeHeader(
166 (MethodDoc) methods.get(currentMethodIndex),
167 methodDetailsTree);
168 buildChildren(node, methodDocTree);
169 methodDetailsTree.addContent(writer.getMethodDoc(
170 methodDocTree, (currentMethodIndex == size - 1)));
171 }
172 memberDetailsTree.addContent(
173 writer.getMethodDetails(methodDetailsTree));
174 }
175 }
177 /**
178 * Build the signature.
179 *
180 * @param node the XML element that specifies which components to document
181 * @param methodDocTree the content tree to which the documentation will be added
182 */
183 public void buildSignature(XMLNode node, Content methodDocTree) {
184 methodDocTree.addContent(
185 writer.getSignature((MethodDoc) methods.get(currentMethodIndex)));
186 }
188 /**
189 * Build the deprecation information.
190 *
191 * @param node the XML element that specifies which components to document
192 * @param methodDocTree the content tree to which the documentation will be added
193 */
194 public void buildDeprecationInfo(XMLNode node, Content methodDocTree) {
195 writer.addDeprecated(
196 (MethodDoc) methods.get(currentMethodIndex), methodDocTree);
197 }
199 /**
200 * Build the comments for the method. Do nothing if
201 * {@link Configuration#nocomment} is set to true.
202 *
203 * @param node the XML element that specifies which components to document
204 * @param methodDocTree the content tree to which the documentation will be added
205 */
206 public void buildMethodComments(XMLNode node, Content methodDocTree) {
207 if (!configuration.nocomment) {
208 MethodDoc method = (MethodDoc) methods.get(currentMethodIndex);
210 if (method.inlineTags().length == 0) {
211 DocFinder.Output docs = DocFinder.search(
212 new DocFinder.Input(method));
213 method = docs.inlineTags != null && docs.inlineTags.length > 0 ?
214 (MethodDoc) docs.holder : method;
215 }
216 //NOTE: When we fix the bug where ClassDoc.interfaceTypes() does
217 // not pass all implemented interfaces, holder will be the
218 // interface type. For now, it is really the erasure.
219 writer.addComments(method.containingClass(), method, methodDocTree);
220 }
221 }
223 /**
224 * Build the tag information.
225 *
226 * @param node the XML element that specifies which components to document
227 * @param methodDocTree the content tree to which the documentation will be added
228 */
229 public void buildTagInfo(XMLNode node, Content methodDocTree) {
230 writer.addTags((MethodDoc) methods.get(currentMethodIndex),
231 methodDocTree);
232 }
234 /**
235 * Return the method writer for this builder.
236 *
237 * @return the method writer for this builder.
238 */
239 public MethodWriter getWriter() {
240 return writer;
241 }
242 }