DocumentationDeclared


1   /*
2    * Project: BeautyJ - Customizable Java Source Code Transformer
3    * Class:   de.gulden.util.javasource.DocumentationDeclared
4    * Version: 1.1
5    *
6    * Date:    2004-09-29
7    *
8    * Note:    Contains auto-generated Javadoc comments created by BeautyJ.
9    *  
10   * This is licensed under the GNU General Public License (GPL)
11   * and comes with NO WARRANTY. See file license.txt for details.
12   *
13   * Author:  Jens Gulden
14   * Email:   beautyj@jensgulden.de
15   */
16  
17  package de.gulden.util.javasource;
18  
19  import de.gulden.util.javasource.jjt.Node;
20  import de.gulden.util.javasource.jjt.*;
21  import de.gulden.util.xml.XMLToolbox;
22  import javax.xml.parsers.*;
23  import org.w3c.dom.*;
24  import java.io.*;
25  import java.util.*;
26  
27  /**
28   * Class DocumentationDeclared.
29   *  
30   * @author  Jens Gulden
31   * @version  1.1
32   */
33  public class DocumentationDeclared extends Documentation {
34  
35      // ------------------------------------------------------------------------
36      // --- final static field                                               ---
37      // ------------------------------------------------------------------------
38  
39      /**
40       * Constant workaroundReplaceSingleStar.
41       */
42      private static final String   workaroundReplaceSingleStar = "###SINGLE-STAR###";
43  
44  
45      // ------------------------------------------------------------------------
46      // --- fields                                                           ---
47      // ------------------------------------------------------------------------
48  
49      /**
50       * The my documentation tagged.
51       */
52      public Vector myDocumentationTagged;
53  
54      /**
55       * The my source object declared.
56       */
57      public SourceObjectDeclared mySourceObjectDeclared;
58  
59  
60      // ------------------------------------------------------------------------
61      // --- constructor                                                      ---
62      // ------------------------------------------------------------------------
63  
64      /**
65       * Creates a new instance of DocumentationDeclared.
66       */
67      public DocumentationDeclared() {
68          myDocumentationTagged=new Vector();
69      }
70  
71  
72      // ------------------------------------------------------------------------
73      // --- methods                                                          ---
74      // ------------------------------------------------------------------------
75  
76      /**
77       * Returns the tags.
78       */
79      public Enumeration getTags() {
80          return myDocumentationTagged.elements();
81      }
82  
83      public DocumentationTagged findTag(String   tag, String   item) {
84          for (Enumeration e=myDocumentationTagged.elements();e.hasMoreElements();) {
85              DocumentationTagged dt=(DocumentationTagged)e.nextElement();
86              if (
87                  dt.getTag().equals(tag)
88                  &&
89                  (
90                      ( (item==null) && (dt.getItem()==null) )
91                      ||
92                      ( (item!=null) && (dt.getItem()!=null) && (item.equals(dt.getItem())) )
93                  )
94              ) {
95                  return dt;
96              }
97          }
98          return null;
99      }
100 
101     /**
102      * Adds a tag.
103      */
104     public void addTag(DocumentationTagged tag) {
105         myDocumentationTagged.addElement(tag);
106     }
107 
108     /**
109      * Removes a tag.
110      */
111     public void removeTag(DocumentationTagged tag) {
112         myDocumentationTagged.removeElement(tag);
113     }
114 
115     /**
116      * Removes all tags.
117      */
118     public void removeAllTags() {
119         myDocumentationTagged.removeAllElements();
120     }
121 
122     /**
123      * Returns the source object declared.
124      */
125     public SourceObjectDeclared getSourceObjectDeclared() {
126         return mySourceObjectDeclared;
127     }
128 
129     /**
130      * Sets the source object declared.
131      */
132     public void setSourceObjectDeclared(SourceObjectDeclared sourceObjectDeclared) {
133         this.mySourceObjectDeclared = sourceObjectDeclared;
134     }
135 
136     /**
137      * Extends Documentation.setRaw(String raw).
138      */
139     public void setRaw(String   raw) {
140                 super.setRaw(raw);
141                 try {
142                     raw = raw.trim();
143                     // workaround 1: a Javadoc-comment might end with ***..**/ (multiple stars). Remove all additional stars so that comments ends cleanly with "*/" (otherwise stars will be seen as part of the comment text, which is very most likely not intended in such case)
144                     while (raw.charAt(raw.length()-3)=='*') {
145                         raw = raw.substring(0, raw.length()-3) + "*/";
146                     }
147                     // workaround 2: Javadoc-parser fails if no blank before ending */, so insert if needed (will not distort parse results, will be trimmed anyway)
148                     if (raw.charAt(raw.length()-3)!=' ') {
149                         raw = raw.substring(0, raw.length()-2) +" */";
150                     }
151                     // workaround 3: avoid single " * " occurrences in Javadoc, replace now and replace-back later
152                     raw = workaroundAvoidSingleStar(raw);
153                     // parse
154                     Node docnode=JavadocParser.parse(raw);
155                     this.text = getTextFromNode(docnode.getChild(JavadocParserTreeConstants.JJTDESCRIPTION)).trim();
156                     Node[] tags=docnode.getChildren(JavadocParserTreeConstants.JJTTAG);
157                     for (int i=0;i<tags.length;i++) {
158                         String   tag;
159                         String   tagItem;
160                         String   tagText;
161                         tag=tags[i].getValue();
162                         Node itemNode=tags[i].getChild(JavadocParserTreeConstants.JJTTAGITEM);
163                         if (itemNode!=null) {
164                             tagItem=itemNode.getChild(JavadocParserTreeConstants.JJTWORD).getValue();
165                         }
166                         else {
167                             tagItem=null;
168                         }
169                         tagText=getTextFromNode(tags[i]).trim();
170                         DocumentationTagged dt=new DocumentationTagged();
171                         dt.setTag(tag);
172                         dt.setItem(tagItem);
173                         dt.setText(tagText);
174                         this.addTag(dt);
175                     }
176                     return;
177                 }
178                 catch (TokenMgrError te) {
179                     // fallthrough
180                 }
181                 catch (ParseException pe) {
182                     // fallthrough
183                 }
184                 text="... warning: could not parse javadoc comment ...";
185                 String   msg = "warning: could not parse javadoc comment, warning message inserted instead";
186                 SourceObjectDeclared sourceObjectDeclared = getSourceObjectDeclared();
187                 if (sourceObjectDeclared != null) {
188                     Class   declaringClass = sourceObjectDeclared.getDeclaringClass();
189                     String   n = sourceObjectDeclared.getName();
190                     msg += " ["+ ( declaringClass!=null ? declaringClass.getName()+(n!=null?".":"") : "") + (n!=null?n:"") + "]";
191                 }
192                 System.err.println(msg);
193     }
194 
195     /**
196      * Initialize this object from XML.
197      *  
198      * @param element The corresponding XML tag.
199      * @throws IOException if an i/o error occurs
200      */
201     public void initFromXML(Element element) throws IOException {
202         // to be extended (not overwritten) by subclasses
203         name=element.getAttribute("name"); // adjust name
204         setText(XMLToolbox.getText(element));
205         myDocumentationTagged.removeAllElements();
206         NodeList nl=XMLToolbox.getChildren(element,"tag");
207         for (int i=0;i<nl.getLength();i++) {
208             DocumentationTagged dt=new DocumentationTagged();
209             dt.initFromXML((Element)nl.item(i));
210             myDocumentationTagged.addElement(dt);
211         }
212     }
213 
214     /**
215      * Output this object as XML.
216      *  
217      * @return  The XML tag.
218      * @see  #initFromXML
219      */
220     public Element buildXML(Document d) {
221         Element e=super.buildXML(d);
222         for (Enumeration ee=getTags();ee.hasMoreElements();) {
223             DocumentationTagged dt=(DocumentationTagged)ee.nextElement();
224             String   tag=dt.getTag();
225             if (!(tag.equals("@param") // these are handled at the referenced SourceObjectDeclared's
226             ||tag.equals("@exception")
227             ||tag.equals("@throws")
228             )) {
229                 e.appendChild(dt.buildXML(d));
230             }
231         }
232         return e;
233     }
234 
235 
236     // ------------------------------------------------------------------------
237     // --- static methods                                                   ---
238     // ------------------------------------------------------------------------
239 
240     protected static String   workaroundAvoidSingleStar(String   s) {
241         int pos = s.indexOf('*');
242         while (pos != -1) {
243             if (s.charAt(pos+1)!='/') { // not the very end of the comment
244                 int linestart = s.lastIndexOf(nl, pos) + 1; // will result in 0 for 'not found' which is wanted
245                 String   beforeStar = s.substring(linestart, pos);
246                 //if (containsText(beforeStar)) { // found a star to replace
247                 if ((beforeStar.indexOf('*')!=-1) && (!beforeStar.equals("/*"))) {
248                     s = s.substring(0, pos) + workaroundReplaceSingleStar + s.substring(pos+1);
249                     return workaroundAvoidSingleStar(s);
250                 }
251                 pos = s.indexOf('*', pos+1);
252             } else {
253                 pos = -1;
254             }
255         }
256         return s;
257     }
258 
259     protected static String   workaroundRestoreSingleStar(String   s) {
260         int pos = s.indexOf(workaroundReplaceSingleStar);
261         if (pos != -1) {
262             return s.substring(0, pos) + "*" + workaroundRestoreSingleStar(s.substring(pos+workaroundReplaceSingleStar.length()));
263         } else {
264         return s;
265         }
266     }
267 
268     /**
269      * Returns the text from node.
270      */
271     private static String   getTextFromNode(Node n) {
272         StringBuffer   sb=new StringBuffer  ();
273         Node[] lines=n.getChildren(JavadocParserTreeConstants.JJTLINE);
274         for (int i=0;i<lines.length;i++) {
275             Node[] words=lines[i].getChildren(JavadocParserTreeConstants.JJTWORD);
276             for (int j=0;j<words.length;j++) {
277                 sb.append( workaroundRestoreSingleStar( words[j].getValue() ) );
278                 if (j<words.length-1) {
279                     sb.append(" ");
280                 }
281             }
282             sb.append("\n");
283         }
284         return sb.toString();
285     }
286 
287 } // end DocumentationDeclared
288
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags