KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > aspectj > tools > ajdoc > Comment


1 /* -*- Mode: JDE; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
2  *
3  * This file is part of the debugger and core tools for the AspectJ(tm)
4  * programming language; see http://aspectj.org
5  *
6  * The contents of this file are subject to the Mozilla Public License
7  * Version 1.1 (the "License"); you may not use this file except in
8  * compliance with the License. You may obtain a copy of the License at
9  * either http://www.mozilla.org/MPL/ or http://aspectj.org/MPL/.
10  *
11  * Software distributed under the License is distributed on an "AS IS" basis,
12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
13  * for the specific language governing rights and limitations under the
14  * License.
15  *
16  * The Original Code is AspectJ.
17  *
18  * The Initial Developer of the Original Code is Xerox Corporation. Portions
19  * created by Xerox Corporation are Copyright (C) 1999-2002 Xerox Corporation.
20  * All Rights Reserved.
21  */
22 package org.aspectj.tools.ajdoc;
23
24 import com.sun.javadoc.Doc;
25 import com.sun.javadoc.ParamTag;
26 import com.sun.javadoc.SeeTag;
27 import com.sun.javadoc.SerialFieldTag;
28 import com.sun.javadoc.Tag;
29 import com.sun.javadoc.ThrowsTag;
30
31 import java.util.ArrayList JavaDoc;
32 import java.util.Iterator JavaDoc;
33 import java.util.List JavaDoc;
34 import java.util.Locale JavaDoc;
35
36 public class Comment {
37     
38     /** The parsed comment text. */
39     private String JavaDoc commentText;
40
41     /** The raw comment text. */
42     private String JavaDoc rawCommentText;
43
44     /** The list of tags. */
45     private List JavaDoc tags;
46
47     /** The Doc to which the Comment belongs. */
48     private Doc doc;
49
50     /** The Locale in which this comment resides. */
51     private Locale JavaDoc loc;
52
53     /** The ErrPrinter used by this Comment to output messages. */
54     private ErrPrinter err;
55
56     public Comment(Doc doc, String JavaDoc formalComment) {
57         this(doc, formalComment, ErrPrinter.instance);
58     }
59
60     public Comment(Doc doc, String JavaDoc formalComment, ErrPrinter err) {
61         this(doc, formalComment, err, Locale.US);
62     }
63
64     public Comment(Doc doc, String JavaDoc formalComment, ErrPrinter err, Locale JavaDoc loc) {
65         this.rawCommentText = Util.rawCommentText(formalComment);
66         this.commentText = Util.commentText(rawCommentText);
67         this.doc = doc;
68         this.err = err;
69         this.loc = loc;
70     }
71
72     /**
73      * Returns the parsed comment text.
74      *
75      * @return the parsed comment text.
76      */
77     public String JavaDoc commentText() {
78         return commentText;
79     }
80
81     /**
82      * Returns the full unprocessed text of the comment.
83      *
84      * @return the full unprocessed text of the comment.
85      */
86     public String JavaDoc getRawCommentText() {
87         return rawCommentText;
88     }
89
90     /**
91      * Sets the comment text.
92      *
93      * @param commentText the new comment text.
94      */
95     public void setCommentText(String JavaDoc commentText) {
96         this.commentText = commentText;
97     }
98     
99     /**
100      * Returns the raw comment text.
101      *
102      * @return the raw comment text.
103      */
104     public String JavaDoc rawCommentText() {
105         return rawCommentText;
106     }
107
108     /**
109      * Sets the raw comment text.
110      *
111      * @param rawCommentText the new raw comment text.
112      */
113     public void setRawCommentText(String JavaDoc rawCommentText) {
114         this.rawCommentText = rawCommentText;
115     }
116
117     /**
118      * Returns all this comment's tags.
119      *
120      * @return a List of tags whose elements are Comment instances
121      */
122     public List JavaDoc getTags() {
123         if (tags == null) {
124             tags = findTags();
125         }
126         return tags;
127     }
128     
129     /**
130      * Sets the Doc for this comment.
131      *
132      * @param doc the new Doc.
133      */
134     public void setDoc(Doc doc) {
135         this.doc = doc;
136     }
137
138     /**
139      * Returns the Doc for this comment.
140      *
141      * @return the Doc for this comment.
142      */
143     public Doc doc() {
144         return doc;
145     }
146
147     /**
148      * Sets the locale for this comment.
149      *
150      * @param loc the new locale for this comment.
151      */
152     public void setLocale(Locale JavaDoc loc) {
153         this.loc = loc;
154     }
155
156     /**
157      * Returns the Locale for this comment.
158      *
159      * @return the Locale for this comment.
160      */
161     public Locale JavaDoc locale() {
162         return loc;
163     }
164     
165     /**
166      * Sets the ErrPrinter for this comment.
167      *
168      * @param err the new ErrPrinter for this comment.
169      */
170     public void setErr(ErrPrinter err) {
171         this.err = err;
172     }
173
174     /**
175      * Returns the ErrPrinter for this comment.
176      *
177      * @return the ErrPrinter for this comment.
178      */
179     public ErrPrinter err() {
180         return err;
181     }
182
183     /**
184      * Initializes the Doc, Locale, and ErrPrinter.
185      *
186      * @param doc the new Doc.
187      * @param loc the new Locale.
188      * @param err the new ErrPrinter.
189      */
190     public void init(Doc doc, Locale JavaDoc loc, ErrPrinter err) {
191         setDoc(doc);
192         setLocale(loc);
193         setErr(err);
194     }
195    
196     /**
197      * Returns the comment as an array of Tag.
198      *
199      * @return an array of Tag representing the comment.
200      */
201     public Tag[] inlineTags() {
202         return Util.inlineTags(doc(),
203                                commentText(),
204                                locale(),
205                                err());
206     }
207
208     /**
209      * Returns all tags of the comment whose name equals
210      * <code>tagname</code>.
211      *
212      * @return an array of Tag representing all tags of the
213      * comment whose name equals <code>tagname</code>.
214      */
215     public Tag[] tags(String JavaDoc type) {
216         type = type.startsWith("@") ? type : "@"+type;
217         List JavaDoc result = new ArrayList JavaDoc();
218         Tag tag;
219         for (Iterator JavaDoc i = getTags().iterator(); i.hasNext();) {
220             if ((tag = (Tag)i.next()).kind().equals(type)) {
221                 result.add(tag);
222             }
223         }
224         return (Tag[])result.toArray(new Tag[result.size()]);
225     }
226
227     /**
228      * Returns the param tags describing parameters taken
229      * by this code.
230      *
231      * @return an array of ParamTag representing the
232      * parameters taken by this code.
233      */
234     public ParamTag[] paramTags() {
235         List JavaDoc result = new ArrayList JavaDoc();
236         Tag tag;
237         for (Iterator JavaDoc i = getTags().iterator(); i.hasNext();) {
238             if ((tag = (Tag)i.next()) instanceof ParamTag) {
239                 result.add((ParamTag)tag);
240             }
241         }
242         return (ParamTag[])result.toArray(new ParamTag[result.size()]);
243     }
244     
245     /**
246      * Returns the see tags of the comment.
247      *
248      * @return an array of SeeTag representing the
249      * see tags of the comment.
250      */
251     public SeeTag[] seeTags() {
252         List JavaDoc result = new ArrayList JavaDoc();
253         Tag tag;
254         for (Iterator JavaDoc i = getTags().iterator(); i.hasNext();) {
255             if ((tag = (Tag)i.next()) instanceof SeeTag) {
256                 result.add((SeeTag)tag);
257             }
258         }
259         return (SeeTag[])result.toArray(new SeeTag[result.size()]);
260     }
261
262     /**
263      * Returns the serial field tags for this field.
264      *
265      * @return an array of SerialFieldTag representing the
266      * serial field tags for this field.
267      */
268     public SerialFieldTag[] serialFieldTags() {
269         List JavaDoc result = new ArrayList JavaDoc();
270         Tag tag;
271         for (Iterator JavaDoc i = getTags().iterator(); i.hasNext();) {
272             if ((tag = (Tag)i.next()) instanceof SerialFieldTag) {
273                 result.add((SerialFieldTag)tag);
274             }
275         }
276         return (SerialFieldTag[])result.toArray
277             (new SerialFieldTag[result.size()]);
278     }
279
280     /**
281      * Returns the throw tags describing exceptions thrown
282      * declared by this code.
283      *
284      * @return an array of ThrowsTag representing the exception
285      * this code declares to throw.
286      */
287     public ThrowsTag[] throwsTags() {
288         List JavaDoc result = new ArrayList JavaDoc();
289         Tag tag;
290         for (Iterator JavaDoc i = getTags().iterator(); i.hasNext();) {
291             if ((tag = (Tag)i.next()) instanceof ThrowsTag) {
292                 result.add((ThrowsTag)tag);
293             }
294         }
295         return (ThrowsTag[])result.toArray
296             (new ThrowsTag[result.size()]);
297     }
298
299     /**
300      * Returns all tags of the comment.
301      *
302      * @return an array of Tag representing all
303      * tags of the comment.
304      */
305     public Tag[] tags() {
306         return (Tag[])getTags().toArray
307             (new Tag[getTags().size()]);
308     }
309
310     /**
311      * Returns the Tags that comprise the first
312      * sentence of the comment.
313      *
314      * @return an array of Tag representing the first
315      * sentence of the comment.
316      */
317     public Tag[] firstSentenceTags() {
318         return Util.firstSentenceTags(doc(),
319                                       commentText(),
320                                       locale(),
321                                       err());
322     }
323
324     /**
325      * Used to lazily initialize the tags of this comment.
326      *
327      * @return a List of tags whose elements of Tag instances
328      * and each represent a tag in this comment.
329      */
330     private List JavaDoc findTags() {
331         return Util.findTags(doc(),
332                              rawCommentText(),
333                              locale(),
334                              err());
335     }
336 }
337
Popular Tags