1 /**
2 * Redistribution and use of this software and associated documentation ("Software"), with or
3 * without modification, are permitted provided that the following conditions are met:
4 *
5 * 1. Redistributions of source code must retain copyright statements and notices. Redistributions
6 * must also contain a copy of this document.
7 *
8 * 2. Redistributions in binary form must reproduce the above copyright notice, this list of
9 * conditions and the following disclaimer in the documentation and/or other materials provided with
10 * the distribution.
11 *
12 * 3. The name "Exolab" must not be used to endorse or promote products derived from this Software
13 * without prior written permission of Intalio, Inc. For written permission, please contact
14 * info@exolab.org.
15 *
16 * 4. Products derived from this Software may not be called "Exolab" nor may "Exolab" appear in
17 * their names without prior written permission of Intalio, Inc. Exolab is a registered trademark of
18 * Intalio, Inc.
19 *
20 * 5. Due credit should be given to the Exolab Project (http://www.exolab.org/).
21 *
22 * THIS SOFTWARE IS PROVIDED BY INTALIO, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESSED OR
23 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
24 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTALIO, INC. OR ITS
25 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
29 * WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 *
31 * Copyright 1999-2003 (C) Intalio, Inc. All Rights Reserved.
32 */
33 package org.exolab.javasource;
34
35 import java.util.Enumeration;
36 import java.util.Vector;
37
38 /**
39 * A class that "SOMEWHAT" represents a JavaDoc Comment.
40 *
41 * @author <a href="mailto:keith AT kvisco DOT com">Keith Visco</a>
42 * @version $Revision$ $Date: 2005-02-26 17:30:28 -0700 (Sat, 26 Feb 2005) $
43 */
44 public final class JDocComment {
45
46 /** An ordered list of descriptors. */
47 private final Vector<JDocDescriptor> _descriptors = new Vector<JDocDescriptor>();
48
49 /** The internal buffer for this JDocComment. */
50 private final StringBuffer _comment = new StringBuffer();
51
52
53 /**
54 * Creates a new JavaDoc Comment.
55 */
56 public JDocComment() {
57 super();
58 }
59
60 /**
61 * Creates a new JavaDoc Comment and initializie it with given JDocDescriptor.
62 *
63 * @param jdesc The JDocDescriptor to add.
64 */
65 public JDocComment(final JDocDescriptor jdesc) {
66 this();
67 addDescriptor(jdesc);
68 }
69
70 /**
71 * Adds the given JDocDescriptor to this JDocComment.
72 *
73 * @param jdesc The JDocDescriptor to add.
74 */
75 public void addDescriptor(final JDocDescriptor jdesc) {
76 if (jdesc == null) {
77 return;
78 }
79 // -- on the fly sorting of descriptors
80 if (_descriptors.isEmpty()) {
81 _descriptors.add(jdesc);
82 return;
83 }
84
85 for (int i = 0; i < _descriptors.size(); i++) {
86 JDocDescriptor jdd = _descriptors.elementAt(i);
87
88 short compare = jdesc.compareTo(jdd);
89
90 switch (compare) {
91 case 0: // equal
92 _descriptors.insertElementAt(jdesc, i + 1);
93 return;
94 case -1: // -- less than
95 _descriptors.insertElementAt(jdesc, i);
96 return;
97 default:
98 // -- keep looking
99 break;
100 }
101 }
102
103 // -- if we make it here we need to add
104 _descriptors.addElement(jdesc);
105 }
106
107 /**
108 * Appends the provided comment String to this JDocComment.
109 *
110 * @param comment The comment to append.
111 */
112 public void appendComment(final String comment) {
113 _comment.append(comment);
114 }
115
116 /**
117 * Returns the String value of this JDocComment.
118 *
119 * @return The String value of this JDocComment.
120 */
121 public String getComment() {
122 return _comment.toString();
123 }
124
125 /**
126 * Sets the comment String of this JDocComment.
127 *
128 * @param comment The comment String of this JDocComment.
129 */
130 public void setComment(final String comment) {
131 _comment.setLength(0);
132 _comment.append(comment);
133 }
134
135 /**
136 * Returns an Enumeration of the parameters of this JDocComment.
137 *
138 * @return An Enumeration of the parameters of this JDocComment.
139 */
140 public Enumeration<JDocDescriptor> getDescriptors() {
141 return _descriptors.elements();
142 }
143
144 /**
145 * Returns the length of the JavaDoc comment in characters.
146 *
147 * @return The length of the JavaDoc comment in characters.
148 */
149 public int getLength() {
150 return _comment.length();
151 }
152
153 /**
154 * Returns the Parameter Descriptor associated with the given name.
155 *
156 * @param name The name whose ParamDescriptor is being searched for.
157 * @return the Parameter Descriptor associated with the given name.
158 */
159 public JDocDescriptor getParamDescriptor(final String name) {
160 if (name == null) {
161 return null;
162 }
163
164 for (JDocDescriptor jdd : _descriptors) {
165 if (jdd.getType() == JDocDescriptor.PARAM) {
166 if (name.equals(jdd.getName())) {
167 return jdd;
168 }
169 }
170 }
171 return null;
172 }
173
174
175 /**
176 * Prints this JavaDoc comment using the given JSourceWriter.
177 *
178 * @param jsw The JSourceWriter to print to.
179 */
180 public void print(final JSourceWriter jsw) {
181 // -- I reuse JComment for printing
182 JComment jComment = new JComment(JComment.JAVADOC_STYLE);
183
184 jComment.setComment(_comment.toString());
185
186 // -- force a separating "*" for readability
187 if (!_descriptors.isEmpty()) {
188 jComment.appendComment("\n");
189 }
190
191 for (JDocDescriptor jdd : _descriptors) {
192 jComment.appendComment("\n");
193 jComment.appendComment(jdd.toString());
194 }
195 jComment.print(jsw);
196 }
197
198 public String toString() {
199 return "/**\n" + " * " + " */\n";
200 }
201
202 }