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 (C) Intalio, Inc. All Rights Reserved.
32 */
33 package org.exolab.javasource;
34
35 /**
36 * A class that represents a Java comment.
37 *
38 * @author <a href="mailto:keith AT kvisco DOT com">Keith Visco</a>
39 * @version $Revision$ $Date: 2005-02-26 17:30:28 -0700 (Sat, 26 Feb 2005) $
40 */
41 public final class JComment {
42 // --------------------------------------------------------------------------
43
44 /**
45 * The auto style, allows this JComment to automatically choose a style for this comment.
46 */
47 public static final short AUTO_STYLE = 0;
48
49 /** The block comment style. \/* *\/ */
50 public static final short BLOCK_STYLE = 1;
51
52 /** The line comment style. \/\/ */
53 public static final short LINE_STYLE = 2;
54
55 /** The header style, similiar to block, but with an '*' at the start of each line. */
56 public static final short HEADER_STYLE = 3;
57
58 /** Similiar to HEADER_STYLE. But starts with: \/** */
59 public static final short JAVADOC_STYLE = 4;
60
61 private static final String START_BLOCK = "/*";
62 private static final String END_BLOCK = " */";
63
64 private static final String START_JAVADOC = "/**";
65 private static final String END_JAVADOC = " */";
66
67 private static final String ASTERIX_PREFIX = " * ";
68 private static final String LINE_COMMENT_PREFIX = "// ";
69 private static final String SPACE_PREFIX = " ";
70
71 // --------------------------------------------------------------------------
72
73 /** The style of this comment. */
74 private short _style = AUTO_STYLE;
75
76 /** The main comment for this JDocComment. */
77 private StringBuffer _comment = null;
78
79 /** The maximum number of characters per line. */
80 protected static final int MAX_LENGTH = 65;
81
82 /** The maximum number of characters to indent comments. */
83 protected static final int MAX_INDENT = 17;
84
85 // --------------------------------------------------------------------------
86
87 /**
88 * Creates a new Java Comment.
89 */
90 public JComment() {
91 super();
92
93 _comment = new StringBuffer();
94 }
95
96 /**
97 * Creates a new Java comment with the given style.
98 *
99 * @param style The desired style.
100 */
101 public JComment(final short style) {
102 this();
103
104 _style = style;
105 }
106
107 // --------------------------------------------------------------------------
108
109 /**
110 * Appends the comment String to this JDocComment.
111 *
112 * @param comment The comment to append.
113 */
114 public void appendComment(final String comment) {
115 _comment.append(comment);
116 }
117
118 /**
119 * Sets the comment String of this JDocComment.
120 *
121 * @param comment The comment String of this JDocComment.
122 */
123 public void setComment(final String comment) {
124 _comment.setLength(0);
125 _comment.append(comment);
126 }
127
128 /**
129 * Sets the style for this JComment.
130 *
131 * @param style The style to use for this JComment.
132 */
133 public void setStyle(final short style) {
134 _style = style;
135 }
136
137 // --------------------------------------------------------------------------
138
139 /**
140 * Prints this JComment using the given JSourceWriter.
141 *
142 * @param jsw The JSourceWriter to print to.
143 */
144 public void print(final JSourceWriter jsw) {
145 if (jsw == null) {
146 return;
147 }
148
149 JCommentFormatter formatter = null;
150
151 // -- calculate comment length
152 short currentIndent = jsw.getIndentSize();
153 int maxLength = MAX_LENGTH - currentIndent;
154
155 // -- a simple check to make sure we have some room to print the comment
156 if (maxLength <= MAX_INDENT) {
157 maxLength = MAX_LENGTH / 2;
158 }
159
160 short resolvedStyle = _style;
161
162 if (_style == AUTO_STYLE) {
163 // -- estimation of number of lines
164 int nbrLines = _comment.length() / maxLength;
165
166 if (nbrLines > 2) {
167 resolvedStyle = BLOCK_STYLE;
168 } else {
169 resolvedStyle = LINE_STYLE;
170 }
171 }
172
173 // -- start comment
174 String prefix = null;
175 String start = null;
176 String end = null;
177
178 switch (resolvedStyle) {
179 case BLOCK_STYLE:
180 start = START_BLOCK;
181 end = END_BLOCK;
182 prefix = SPACE_PREFIX;
183 break;
184 case HEADER_STYLE:
185 start = START_BLOCK;
186 end = END_BLOCK;
187 prefix = ASTERIX_PREFIX;
188 break;
189 case JAVADOC_STYLE:
190 start = START_JAVADOC;
191 end = END_JAVADOC;
192 prefix = ASTERIX_PREFIX;
193 break;
194 default: // -- LINE
195 prefix = LINE_COMMENT_PREFIX;
196 break;
197 }
198
199 if (start != null) {
200 jsw.writeln(start);
201 }
202 // -- print main comment
203 formatter = new JCommentFormatter(_comment.toString(), maxLength, prefix);
204 while (formatter.hasMoreLines()) {
205 jsw.writeln(formatter.nextLine());
206 }
207 if (end != null) {
208 jsw.writeln(end);
209 }
210 jsw.flush();
211 }
212
213 /**
214 * {@inheritDoc}
215 */
216 public String toString() {
217 return "";
218 }
219
220 // --------------------------------------------------------------------------
221 }