KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > HtmlTaglet


1 // HTMLParser Library - A java-based parser for HTML
2 // http://htmlparser.org
3 // Copyright (C) 2006 Derrick Oswald
4 //
5 // Revision Control Information
6 //
7 // $URL: https://svn.sourceforge.net/svnroot/htmlparser/trunk/src/main/java/HtmlTaglet.java $
8 // $Author: derrickoswald $
9 // $Date: 2006-09-16 10:44:17 -0400 (Sat, 16 Sep 2006) $
10 // $Revision: 4 $
11 //
12 // This library is free software; you can redistribute it and/or
13 // modify it under the terms of the Common Public License; either
14 // version 1.0 of the License, or (at your option) any later version.
15 //
16 // This library is distributed in the hope that it will be useful,
17 // but WITHOUT ANY WARRANTY; without even the implied warranty of
18 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 // Common Public License for more details.
20 //
21 // You should have received a copy of the Common Public License
22 // along with this library; if not, the license is available from
23 // the Open Source Initiative (OSI) website:
24 // http://opensource.org/licenses/cpl1.0.php
25
26 import com.sun.tools.doclets.Taglet;
27 import com.sun.javadoc.*;
28 import java.util.Map JavaDoc;
29 import org.htmlparser.util.Translate;
30
31 /**
32  * A JavaDoc Taglet that encodes HTML.
33  * This inline <A HREF="http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/taglet/com/sun/tools/doclets/Taglet.html">taglet</A>
34  * converts HTML into character references for embedding into
35  * <A HREF="http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/index.html">Javadocs</A>.
36  * For example, it converts &lt;html&gt; into &amp;lt;html&amp;gt;.
37  * Typical usage is to embed an example stream of html into the javadoc for
38  * a class or method:
39  * <pre><font color="green">
40  * /**
41  * * Gather DIV elements.
42  * * This method takes &#123;@.html &lt;div&gt;&lt;/div&gt;&#125; pairs and
43  * * constructs nested ...
44  * </font></pre>
45  * This is useful so that the documentation is readable while coding and when
46  * presented in the generated javadocs. Normally, embedding HTML in the
47  * javadoc documentation requires the use of character entity references,
48  * otherwise the HTML is interpreted by the javadoc tool and is stripped out.
49  * The programmer can manually embed the character translations to pass the
50  * HTML through, but the resultant comment is extremely hard to read and
51  * understand when editing the code directly. Plus there is the added
52  * possibility of an incorrect encoding because of the manual step.<p>
53  * The use of this taglet requires a 1.4.x or higher JDK, but it is not
54  * expected that users with older JDKs will be generating javadocs when they
55  * are provided in the distribution.<p>
56  * The name was supposed to be "html", but a warning message is generated
57  * by the javadoc tool if a custom tag name doesn't contain any dots. So the
58  * next best name ".html" is used instead, with a passing resemblance to
59  * directives in nroff.
60  */
61 public class HtmlTaglet implements Taglet
62 {
63     private static final String JavaDoc NAME = ".html";
64
65     /**
66      * Construct a taglet for encoding HTML in doc comments.
67      */
68     public HtmlTaglet ()
69     {
70     }
71     
72     /**
73      * Return the name of this custom taglet.
74      */
75     public String JavaDoc getName ()
76     {
77         return (NAME);
78     }
79     
80     /**
81      * Will return true since <code>&#123;@.html&#125;</code>
82      * can be used in field documentation.
83      * @return <code>true</code> since <code>&#123;@.html&#125;</code>
84      * can be used in field documentation.
85      */
86     public boolean inField ()
87     {
88         return (true);
89     }
90     
91     /**
92      * Will return true since <code>&#123;@.html&#125;</code>
93      * can be used in constructor documentation.
94      * @return <code>true</code> since <code>&#123;@.html&#125;</code>
95      * can be used in constructor documentation.
96      */
97     public boolean inConstructor ()
98     {
99         return (true);
100     }
101     
102     /**
103      * Will return true since <code>&#123;@.html&#125;</code>
104      * can be used in method documentation.
105      * @return <code>true</code> since <code>&#123;@.html&#125;</code>
106      * can be used in method documentation.
107      */
108     public boolean inMethod ()
109     {
110         return (true);
111     }
112     
113     /**
114      * Will return true since <code>&#123;@.html&#125;</code>
115      * can be used in method documentation.
116      * @return <code>true</code> since <code>&#123;@.html&#125;</code>
117      * can be used in overview documentation.
118      */
119     public boolean inOverview ()
120     {
121         return (true);
122     }
123     
124     /**
125      * Will return true since <code>&#123;@.html&#125;</code>
126      * can be used in package documentation.
127      * @return <code>true</code> since <code>&#123;@.html&#125;</code>
128      * can be used in package documentation.
129      */
130     public boolean inPackage ()
131     {
132         return (true);
133     }
134     
135     /**
136      * Will return true since <code>&#123;@.html&#125;</code>
137      * can be used in type documentation (classes or interfaces).
138      * @return true since <code>&#123;@.html&#125;</code>
139      * can be used in type documentation.
140      */
141     public boolean inType ()
142     {
143         return (true);
144     }
145     
146     /**
147      * Will return true since <code>&#123;@.html&#125;</code>
148      * is an inline tag.
149      * @return <code>true</code> since <code>&#123;@.html&#125;</code>
150      * is an inline tag.
151      */
152     
153     public boolean isInlineTag ()
154     {
155         return (true);
156     }
157     
158     /**
159      * Register this Taglet.
160      * @param tagletMap the map to register this tag to.
161      */
162     public static void register (Map JavaDoc tagletMap)
163     {
164         HtmlTaglet tag = new HtmlTaglet ();
165         tagletMap.put (tag.getName (), tag);
166     }
167
168     /**
169      * Format the given string to appear "as is" within a JavaDoc comment.
170      * This method is more complicated than it needs to be, since you might
171      * say why not just use PRE tags surrounding the text. Unfortunately, PRE
172      * is a block level tag that breaks the flow of text, preventing inline
173      * operation. Instead we manually format the whitespace (actually just
174      * spaces and newlines) within the string to preserve the format.
175      */
176     protected String JavaDoc format (String JavaDoc s)
177     {
178         int base;
179         int offset;
180         StringBuffer JavaDoc ret;
181
182         ret = new StringBuffer JavaDoc (512);
183         
184         base = 0;
185         offset = 0;
186         while (-1 != (offset = s.indexOf ('\n', base)))
187         {
188             ret.append (Translate.encode (s.substring (base, offset)));
189             ret.append ("<br>\n");
190             base = offset + 1;
191         }
192         if (base != s.length ())
193             ret.append (Translate.encode (s.substring (base)));
194         
195         s = ret.toString ();
196         ret.setLength (0);
197         for (int i = 0; i < s.length (); i++)
198             if (' ' == s.charAt (i))
199                 ret.append ("&nbsp;");
200             else
201                 ret.append (s.charAt (i));
202             
203         return (ret.toString ());
204     }
205
206     /**
207      * Given the <code>Tag</code> representation of this custom
208      * tag, return its string representation.
209      * @param tag the <code>Tag</code> representation of this custom tag.
210      */
211     public String JavaDoc toString (Tag tag)
212     {
213         return (format (tag.text ()));
214     }
215     
216     /**
217      * Given an array of <code>Tag</code>s representing this custom
218      * tag, return its string representation.
219      * @param tags the array of <code>Tag</code>s representing of this custom tag.
220      */
221     public String JavaDoc toString(Tag[] tags)
222     {
223         StringBuffer JavaDoc ret;
224
225         if (0 == tags.length)
226             return (null);
227         else
228         {
229             ret = new StringBuffer JavaDoc (512);
230             for (int i = 0; i < tags.length; i++)
231             {
232                 if (i > 0)
233                     ret.append ("<br>\n");
234                 ret.append (format (tags[i].text()));
235             }
236             return (ret.toString ());
237         }
238     }
239 }
Popular Tags