Return-Path: 
 <commons-dev-return-9861-qmlist-jakarta-archive-commons-dev=jakarta.apache.org@jakarta.apache.org>
Delivered-To: apmail-jakarta-commons-dev-archive@apache.org
Received: (qmail 77237 invoked from network); 21 Jun 2002 16:57:36 -0000
Received: from unknown (HELO nagoya.betaversion.org) (192.18.49.131)
  by daedalus.apache.org with SMTP; 21 Jun 2002 16:57:36 -0000
Received: (qmail 15014 invoked by uid 97); 21 Jun 2002 16:57:40 -0000
Delivered-To: qmlist-jakarta-archive-commons-dev@jakarta.apache.org
Received: (qmail 14947 invoked by uid 97); 21 Jun 2002 16:57:39 -0000
Mailing-List: contact commons-dev-help@jakarta.apache.org; run by ezmlm
Precedence: bulk
List-Unsubscribe: <mailto:commons-dev-unsubscribe@jakarta.apache.org>
List-Subscribe: <mailto:commons-dev-subscribe@jakarta.apache.org>
List-Help: <mailto:commons-dev-help@jakarta.apache.org>
List-Post: <mailto:commons-dev@jakarta.apache.org>
List-Id: "Jakarta Commons Developers List" <commons-dev.jakarta.apache.org>
Reply-To: "Jakarta Commons Developers List" <commons-dev@jakarta.apache.org>
Delivered-To: mailing list commons-dev@jakarta.apache.org
Received: (qmail 14936 invoked by uid 97); 21 Jun 2002 16:57:38 -0000
X-Antivirus: nagoya (v4198 created Apr 24 2002)
Date: 21 Jun 2002 16:57:17 -0000
Message-ID: <20020621165717.98982.qmail@icarus.apache.org>
From: jstrachan@apache.org
To: jakarta-commons-sandbox-cvs@apache.org
Subject: cvs commit: jakarta-commons-sandbox/jelly build.xml
X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N
X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N

jstrachan    2002/06/21 09:57:17

  Modified:    jelly/src/java/org/apache/commons/jelly TagSupport.java
               jelly/src/script makeTagDoc.jelly
               jelly    build.xml
  Added:       jelly/src/java/org/apache/commons/jelly/util
                        TagXMLDoclet.java
  Log:
  Fixed the tag doclet so that the build can now generate reasonable documentation for all the current tag libraries as part of the maven build.
  Some javadoc tags like <p> and <a> don't quite get converted to XML unfortunately but its getting close.
  Also the documentation doesn't handle derivation or importing of tags into other taglibs yet.
  
  Revision  Changes    Path
  1.1                  jakarta-commons-sandbox/jelly/src/java/org/apache/commons/jelly/util/TagXMLDoclet.java
  
  Index: TagXMLDoclet.java
  ===================================================================
  /*
   * $Header: /home/cvs/jakarta-commons-sandbox/jelly/src/java/org/apache/commons/jelly/Tag.java,v 1.6 2002/05/17 15:18:12 jstrachan Exp $
   * $Revision: 1.6 $
   * $Date: 2002/05/17 15:18:12 $
   *
   * ====================================================================
   *
   * The Apache Software License, Version 1.1
   *
   * Copyright (c) 1999-2002 The Apache Software Foundation.  All rights
   * reserved.
   *
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   *
   * 1. Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer.
   *
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   *
   * 3. The end-user documentation included with the redistribution, if
   *    any, must include the following acknowlegement:
   *       "This product includes software developed by the
   *        Apache Software Foundation (http://www.apache.org/)."
   *    Alternately, this acknowlegement may appear in the software itself,
   *    if and wherever such third-party acknowlegements normally appear.
   *
   * 4. The names "The Jakarta Project", "Commons", and "Apache Software
   *    Foundation" must not be used to endorse or promote products derived
   *    from this software without prior written permission. For written
   *    permission, please contact apache@apache.org.
   *
   * 5. Products derived from this software may not be called "Apache"
   *    nor may "Apache" appear in their names without prior written
   *    permission of the Apache Group.
   *
   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   * SUCH DAMAGE.
   * ====================================================================
   *
   * This software consists of voluntary contributions made by many
   * individuals on behalf of the Apache Software Foundation.  For more
   * information on the Apache Software Foundation, please see
   * <http://www.apache.org/>.
   * 
   * $Id: Tag.java,v 1.6 2002/05/17 15:18:12 jstrachan Exp $
   */
  
  package org.apache.commons.jelly.util;
  
  import java.beans.Introspector;
  import java.io.*;
  import java.util.*;
  import com.sun.javadoc.*;
  
  import org.dom4j.io.OutputFormat;
  import org.dom4j.io.XMLWriter;
  
  import org.xml.sax.*;
  import org.xml.sax.helpers.*;
  
  /**
   * Main Doclet class to generate Tag Library ML.  
   * 
   * @author <a href="mailto:gopi@aztecsoft.com">Gopinath M.R.</a>
   * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
   */
  
  // #### somehow we need to handle taglib inheritence...
  
  public class TagXMLDoclet extends Doclet {
  
      private String xmlns = "jvx";
      private String encodingFormat="UTF-8";
      private String localName = "javadoc";
      private ContentHandler cm = null;
      private String targetFileName="target/taglib.xml";
      private Attributes emptyAtts = new AttributesImpl();
  
      public TagXMLDoclet (RootDoc root) throws Exception {
          FileWriter writer = new FileWriter(targetFileName);
          try {
              OutputFormat format = OutputFormat.createPrettyPrint();
              XMLWriter xmlWriter = new XMLWriter(writer, format);
              cm = xmlWriter;
              javadocXML(root);
              writer.close();
          } catch (IOException e) {
              writer.close();
              throw e;
          }
      }
  
      /**
       * Generates the xml for the tag libraries
       */
      private void javadocXML(RootDoc root) throws SAXException {
          cm.startElement(xmlns, localName, "tags", emptyAtts);
          PackageDoc[] packageArray = root.specifiedPackages();
  
          // Generate for packages.
          for (int i = 0; i < packageArray.length; ++i) {
              packageXML(packageArray[i]);
          }
  
          cm.endElement(xmlns, localName, "tags");
      }
  
      /**
       * Generates doc for a tag library
       */
      private void packageXML(PackageDoc packageDoc) throws SAXException {
          ClassDoc[] classArray = packageDoc.ordinaryClasses();
          
          // lets see if we find a Tag
          boolean foundTag = false;
          for (int i = 0; i < classArray.length; ++i) {
              ClassDoc classDoc = classArray[i];
              if ( isTag( classArray[i] ) ) {
                  foundTag = true;
                  break;
              }
          }
          if ( ! foundTag ) {
              return;
          }
          
          AttributesImpl atts = new AttributesImpl();
          atts.addAttribute(xmlns, localName, "name", "String", packageDoc.name());
          
          String name = packageDoc.name();
          int idx = name.lastIndexOf('.');
          if ( idx > 0 ) {
              name = name.substring(idx+1);
          }
          atts.addAttribute(xmlns, localName, "prefix", "String", name);
          
          String uri = "jelly:" + name;
          
          atts.addAttribute(xmlns, localName, "uri", "String", uri );
          cm.startElement(xmlns, localName, "library", atts);
  
          // generate Doc element.
          docXML(packageDoc);
  
          // generate tags
          for (int i = 0; i < classArray.length; ++i) {
              if ( isTag( classArray[i] ) ) {
                  tagXML(classArray[i]);
              }
          }
          cm.endElement(xmlns, localName, "library");
      }
  
      /**
       * @return true if this class is a Jelly Tag
       */
      private boolean isTag(ClassDoc classDoc) {
          ClassDoc[] interfaceArray = classDoc.interfaces();
          for (int i = 0; i < interfaceArray.length; ++i) {
              String name = interfaceArray[i].qualifiedName();
              if ("org.apache.commons.jelly.Tag".equals(name)) {
                  return true;
              }
          }
          ClassDoc base = classDoc.superclass();
          if ( base != null ) {
              return isTag(base);
          }
          return false;
      }
      
      /**
       * Generates doc for a tag
       */
      private void tagXML(ClassDoc classDoc) throws SAXException {
          if (classDoc.isAbstract()) {
              return;
          }
          
          AttributesImpl atts = new AttributesImpl();
          atts.addAttribute(xmlns, localName, "className", "String", classDoc.name());
          String name = classDoc.name();
          if ( name.endsWith( "Tag" ) ) {
              name = name.substring(0, name.length() - 3 );
          }
          name = Introspector.decapitalize(name);
          
          atts.addAttribute(xmlns, localName, "name", "String", name);
          cm.startElement(xmlns, localName, "tag", atts);
  
          // generate "doc" sub-element
          docXML(classDoc);
  
          // generate the attributes
          propertiesXML(classDoc);
          
          // generate "method" sub-elements
          cm.endElement(xmlns, localName, "tag");
      }
  
      /**
       * Generates doc for a tag property
       */
      private void propertiesXML(ClassDoc classDoc) throws SAXException {
          MethodDoc[] methodArray = classDoc.methods();
          for (int i = 0; i < methodArray.length; ++i) {
              propertyXML(methodArray[i]);
          }
          ClassDoc base = classDoc.superclass();
          if ( base != null ) {
              propertiesXML( base );
          }
      }
  
  
      /**
       * Generates doc for a tag property
       */
      private void propertyXML(MethodDoc methodDoc) throws SAXException {
          if ( ! methodDoc.isPublic() || methodDoc.isStatic() ) {
              return;
          }
          String name = methodDoc.name();
          if ( ! name.startsWith( "set" ) ) {
              return;
          }
          Parameter[] parameterArray = methodDoc.parameters();
          if ( parameterArray == null || parameterArray.length != 1 ) {
              return;
          }
          Parameter parameter = parameterArray[0];
          
          name = name.substring(3);
          name = Introspector.decapitalize(name);
          
          if ( name.equals( "body") || name.equals( "context" ) || name.equals( "parent" ) ) {
              return;
          }
          AttributesImpl atts = new AttributesImpl();
          atts.addAttribute(xmlns, localName, "name", "String", name);
          atts.addAttribute(xmlns, localName, "type", "String", parameter.typeName());
          
          cm.startElement(xmlns, localName, "attribute", atts);
  
          // maybe do more semantics, like use custom tags to denote if its required, optional etc.
          
          // generate "doc" sub-element
          docXML(methodDoc);
  
          cm.endElement(xmlns, localName, "attribute");
      }
  
      /**
       * Generates doc for element "doc"
       */
      private void docXML(Doc doc) throws SAXException {
          cm.startElement(xmlns, localName, "doc", emptyAtts);
          String commentText = doc.commentText();
          if (! commentText.equals("")) {
              cm.characters(commentText.toCharArray(), 0, commentText.length());
          }
          Tag[] tags = doc.tags();
          for (int i = 0; i < tags.length; ++i) {
              javadocTagXML(tags[i]);
          }
          cm.endElement(xmlns, localName, "doc");
  /*        
          String commentText = "";
          boolean createDoc = false;
          commentText = doc.commentText();
          if (! commentText.equals("")) {
              createDoc = true;
          }
          Tag[] tags = doc.tags();
          if (tags.length > 0) {
              createDoc = true;
          }
          if (createDoc) {
              cm.startElement(xmlns, localName, "doc", emptyAtts);
              if (! commentText.equals("")) {
                  cm.characters(commentText.toCharArray(), 0, commentText.length());
              }
              for (int i = 0; i < tags.length; ++i) {
                  javadocTagXML(tags[i]);
              }
              cm.endElement(xmlns, localName, "doc");
          }
  */        
      }
  
      /**
       * Generates doc for all tag elements.
       */
      private void javadocTagXML(Tag tag) throws SAXException {
          String name = tag.name().substring(1) + "tag";
          if (! tag.text().equals("")) {
              cm.startElement(xmlns, localName, name, emptyAtts);
              cm.characters(tag.text().toCharArray(), 0, tag.text().length());
              cm.endElement(xmlns, localName, name);
          }
      }
  
      public static boolean start(RootDoc root) {
          try {
              new TagXMLDoclet(root);
              return true;
          } catch (Exception e) {
              e.printStackTrace();
              System.exit(1);
              return false;
          }
      }
  }
  
  
  
  1.13      +9 -5      jakarta-commons-sandbox/jelly/src/java/org/apache/commons/jelly/TagSupport.java
  
  Index: TagSupport.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/jelly/src/java/org/apache/commons/jelly/TagSupport.java,v
  retrieving revision 1.12
  retrieving revision 1.13
  diff -u -r1.12 -r1.13
  --- TagSupport.java	14 Jun 2002 10:24:14 -0000	1.12
  +++ TagSupport.java	21 Jun 2002 16:57:17 -0000	1.13
  @@ -115,6 +115,10 @@
           setTrim( shouldTrim );
       }
   
  +    /**
  +     * Sets whether whitespace inside this tag should be trimmed or not. 
  +     * Defaults to true so whitespace is trimmed
  +     */
       public void setTrim(boolean shouldTrim) {
           if ( shouldTrim ) {
               this.shouldTrim = Boolean.TRUE;
  
  
  
  1.3       +43 -11    jakarta-commons-sandbox/jelly/src/script/makeTagDoc.jelly
  
  Index: makeTagDoc.jelly
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/jelly/src/script/makeTagDoc.jelly,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- makeTagDoc.jelly	18 Jun 2002 12:30:10 -0000	1.2
  +++ makeTagDoc.jelly	21 Jun 2002 16:57:17 -0000	1.3
  @@ -5,8 +5,8 @@
   	xmlns:jsl="jelly:jsl" 
   	xmlns:log="jelly:log">
   
  -<x:parse var="doc" xml="target/javadoc.xml"/>
  -<x:set var="packages" select="$doc/javadoc/package[class/implements/interfaceref/@name = 'org.apache.commons.jelly.Tag']"/>    	
  +<x:parse var="doc" xml="target/taglib.xml"/>
  +<x:set var="libraries" select="$doc/tags/library"/>    	
   
   <!-- lets create a JSL stylesheet that we'll use later -->
   <jsl:stylesheet var="docStylesheet">
  @@ -54,10 +54,10 @@
         <th>Library</th>
         <th>Description</th>
       </tr>
  -    <x:forEach select="$packages">
  -    <x:set var="name" select="string(@name)"/>
  +    <x:forEach select="$libraries">
  +    <x:set var="uri" select="string(@uri)"/>
       <tr>
  -      <td><a href="#${name}">${name}</a></td>
  +      <td><a href="#${uri}">${uri}</a></td>
         <td>
         	  <jsl:style stylesheet="${docStylesheet}" select="doc"/>
   	  </td>
  @@ -66,8 +66,9 @@
       </table>
   
       
  -    <x:forEach select="$packages">
  -    <x:set var="name" select="string(@name)"/>
  +    <x:forEach select="$libraries">
  +    <x:set var="name" select="string(@uri)"/>
  +    <x:set var="prefix" select="string(@prefix)"/>
     
       <subsection name="${name}">
       <table>
  @@ -76,10 +77,10 @@
         <th>Description</th>
       </tr>
       
  -    <x:forEach select="class[@extensibility!='abstract' and implements/interfaceref/@name = 'org.apache.commons.jelly.Tag']">
  +    <x:forEach select="tag">
       <x:set var="tagName" select="string(@name)"/>
   	<tr>
  -    	<td><a href="#${tagName}">${tagName}</a></td>
  +    	<td><a href="#${prefix}:${tagName}">${tagName}</a></td>
           <td>        
         	  <jsl:style stylesheet="${docStylesheet}" select="doc"/>
   		</td>
  @@ -92,15 +93,46 @@
       
       </section>
         
  -      
  +            
   
   	<section name="Tags">	
      	  <p>
           [<a href="#Tag Libraries">tag libraries</a>]
           [<a href="#Tags">tags</a>]
         </p>
  -    </section>
       
  +    <x:forEach select="$libraries">
  +    <x:set var="prefix" select="string(@prefix)"/>
  +      <x:forEach select="tag">
  +      <x:set var="tagName" select="string(@name)"/>
  +
  +
  +	    <subsection name="${prefix}:${tagName}">
  +	    <table>
  +	    <tr>
  +	      <th>Attribute Name</th>
  +	      <th>Type</th>
  +	      <th>Description</th>
  +	    </tr>
  +	    
  +	    <x:forEach select="attribute">
  +		<tr>
  +	    	<td><x:expr select="@name"/></td>
  +	    	<td><x:expr select="@type"/></td>
  +	        <td>        
  +	      	  <jsl:style stylesheet="${docStylesheet}" select="doc"/>
  +			</td>
  +		</tr>
  +	    </x:forEach>
  +	    </table>
  +	    </subsection>
  +    
  +    
  +    
  +      </x:forEach>
  +    </x:forEach>
  +    </section>
  +  
     </body>
   </document>
   
  
  
  
  1.53      +16 -3     jakarta-commons-sandbox/jelly/build.xml
  
  Index: build.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/jelly/build.xml,v
  retrieving revision 1.52
  retrieving revision 1.53
  diff -u -r1.52 -r1.53
  --- build.xml	21 Jun 2002 02:57:17 -0000	1.52
  +++ build.xml	21 Jun 2002 16:57:17 -0000	1.53
  @@ -215,8 +215,7 @@
   
   
   	<!-- runs the XML doclet -->	
  -	<target name="xml.doclet" depends="compile">
  -	  <mkdir dir="target/xmldoclet"/>	   
  +	<target name="xml-doclet" depends="compile">
   	  <path id="doclet.classpath">
   	    <pathelement path="${maven.build.dest}"/>
   	    <path refid="maven.dependency.classpath"/>
  @@ -229,7 +228,21 @@
   	  </javadoc>
   	</target>
   	
  -   <target name="doc-tags" depends="compile" 
  +	<!-- runs the Tag doclet -->	
  +	<target name="tag-doclet" depends="compile">
  +	  <path id="doclet.classpath">
  +	    <pathelement path="${maven.build.dest}"/>
  +	    <path refid="maven.dependency.classpath"/>
  +	  </path>
  +	  <javadoc 
  +	  	sourcepath="src/java" 
  +	  	packagenames="org.apache.commons.jelly.tags.*"
  +	  	doclet="org.apache.commons.jelly.util.TagXMLDoclet"
  +	  	docletpathref="doclet.classpath">
  +	  </javadoc>
  +	</target>
  +	
  +   <target name="doc-tags" depends="tag-doclet" 
         description="Generates the tag documentation">
       <mkdir dir="target/generated-xdocs"/>
   	<jelly file="src/script/makeTagDoc.jelly" output="target/generated-xdocs/tags.xml"/> 
  
  
  

--
To unsubscribe, e-mail:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>