diff --git a/jellydoc/.cvsignore b/jellydoc/.cvsignore new file mode 100644 index 00000000..e5e33942 --- /dev/null +++ b/jellydoc/.cvsignore @@ -0,0 +1,3 @@ +target +velocity.log +maven.log diff --git a/jellydoc/plugin.jelly b/jellydoc/plugin.jelly new file mode 100644 index 00000000..2df968d3 --- /dev/null +++ b/jellydoc/plugin.jelly @@ -0,0 +1,78 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Generating jellydoc for packages ${maven.jellydoc.packages} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/jellydoc/plugin.properties b/jellydoc/plugin.properties new file mode 100644 index 00000000..25b03fbe --- /dev/null +++ b/jellydoc/plugin.properties @@ -0,0 +1,11 @@ +# ------------------------------------------------------------------- +# P L U G I N P R O P E R I E S +# ------------------------------------------------------------------- +# Activity log plugin. +# ------------------------------------------------------------------- + +maven.build.dir = ${basedir}/target + +maven.docs.outputencoding = ISO-8859-1 + +maven.activitylog.range = 30 diff --git a/jellydoc/project.xml b/jellydoc/project.xml new file mode 100644 index 00000000..abf12aff --- /dev/null +++ b/jellydoc/project.xml @@ -0,0 +1,95 @@ + + + + ${basedir}/../project.xml + 3 + maven-jellydoc-plugin + Maven JellyDoc Plug-in + 1.0-SNAPSHOT + + + jakarta + + + Creates a JavaDoc like report for any Jelly Tags used in a project. + + + + + http://jakarta.apache.org/turbine/maven/reference/plugins/jellydoc/ + http://jira.werken.com/BrowseProject.jspa?id=10030 + jakarta.apache.org + /www/jakarta.apache.org/turbine/maven/reference/plugins/jellydoc/ + /www/jakarta.apache.org/builds/jakarta-turbine-maven/ + + + + James Strachan + jstrachan + jstrachan@apache.org + SpiritSoft, Inc. + + Java Developer + + + + + + + + + commons-jelly + commons-jelly-tags-jsl + SNAPSHOT + http://jakarta.apache.org/commons/jelly/tags/jsl/ + + root.maven + + + + + commons-jelly + commons-jelly-tags-xml + SNAPSHOT + http://jakarta.apache.org/commons/jelly/tags/xml/ + + root.maven + + + + + javadoc + 1.3 + + root.maven + + + + + nekohtml + 0.7.1 + + root.maven + + + + + + dom4j + 1.4-dev-8 + http://www.dom4j.org/ + + + xml-apis + 1.0.b2 + http://xml.apache.org/xerces2-j/ + + + xerces + 2.2.1 + http://xml.apache.org/xerces2-j/ + + + + + diff --git a/jellydoc/src/main/org/apache/maven/jellydoc/TagXMLDoclet.java b/jellydoc/src/main/org/apache/maven/jellydoc/TagXMLDoclet.java new file mode 100644 index 00000000..7ed31d51 --- /dev/null +++ b/jellydoc/src/main/org/apache/maven/jellydoc/TagXMLDoclet.java @@ -0,0 +1,396 @@ +/* + * /home/cvs/maven-plugins/jellydoc/src/main/org/apache/maven/jellydoc/TagXMLDoclet.java,v 1.1 2003/02/07 12:10:44 jstrachan Exp + * 1.1 + * 2003/02/07 12:10:44 + * + * ==================================================================== + * + * The Apache Software License, Version 1.1 + * + * Copyright (c) 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 + * . + * + * TagXMLDoclet.java,v 1.1 2003/02/07 12:10:44 jstrachan Exp + */ + +package org.apache.maven.jellydoc; + +import java.beans.Introspector; +import java.io.FileOutputStream; +import java.io.IOException; +import java.io.StringReader; + +import org.cyberneko.html.parsers.SAXParser; +import org.dom4j.io.OutputFormat; +import org.dom4j.io.XMLWriter; +import org.xml.sax.Attributes; +import org.xml.sax.ContentHandler; +import org.xml.sax.InputSource; +import org.xml.sax.SAXException; +import org.xml.sax.helpers.AttributesImpl; +import org.xml.sax.helpers.DefaultHandler; + +import com.sun.javadoc.ClassDoc; +import com.sun.javadoc.Doc; +import com.sun.javadoc.Doclet; +import com.sun.javadoc.MethodDoc; +import com.sun.javadoc.PackageDoc; +import com.sun.javadoc.Parameter; +import com.sun.javadoc.RootDoc; +import com.sun.javadoc.SeeTag; +import com.sun.javadoc.Tag; + +/** + * Main Doclet class to generate Tag Library ML. + * + * @author Gopinath M.R. + * @author James Strachan + * @author Rodney Waldhoff + */ + +// #### 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 { + FileOutputStream writer = new FileOutputStream(targetFileName); + OutputFormat format = OutputFormat.createPrettyPrint(); + XMLWriter xmlWriter = new XMLWriter(writer, format); + try { + cm = xmlWriter; + cm.startDocument(); + javadocXML(root); + cm.endDocument(); + xmlWriter.close(); + } + catch (IOException e) { + xmlWriter.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); + // handle the "comment" part, including {@link} tags + { + Tag[] tags = doc.inlineTags(); + for(int i=0;i. + * + * XMLDoclet.java,v 1.1 2003/02/07 12:10:44 jstrachan Exp + */ + +package org.apache.maven.jellydoc; + +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 JavaDocXML. This doclet generates the + * document conforming to DTD specified in javadoc-v04draft.dtd. + * @author Gopinath M.R. + * @author James Strachan + */ + +public class XMLDoclet extends Doclet { + + private String xmlns = "jvx"; + private String encodingFormat="UTF-8"; + private String localName = "javadoc"; + private ContentHandler cm = null; + private String targetFileName="target/javadoc.xml"; + private Attributes emptyAtts = new AttributesImpl(); + + public XMLDoclet (RootDoc root) throws Exception { + FileOutputStream writer = new FileOutputStream(targetFileName); + OutputFormat format = OutputFormat.createPrettyPrint(); + XMLWriter xmlWriter = new XMLWriter(writer, format); + try { + cm = xmlWriter; + cm.startDocument(); + javadocXML(root); + cm.endDocument(); + xmlWriter.close(); + } + catch (IOException e) { + xmlWriter.close(); + throw e; + } + } + + /** + * Generates the xml data for the top element. + * <!ELEMENT javadoc (package*, class*, interface*)> + */ + private void javadocXML(RootDoc root) throws SAXException { + cm.startElement(xmlns, localName, "javadoc", emptyAtts); + PackageDoc[] packageArray = root.specifiedPackages(); + + // Generate for packages. + for (int i = 0; i < packageArray.length; ++i) { + packageXML(packageArray[i]); + } + + // Generate for classes. + ClassDoc[] classArray = root.specifiedClasses(); + Vector interfaceVector = new Vector(); + for (int i = 0; i < classArray.length; ++i) { + if (classArray[i].isInterface()) { + interfaceVector.addElement(classArray[i]); + } else { + classXML(classArray[i]); + } + } + + // Generate for interfaces. + Enumeration interfaceEnum = interfaceVector.elements(); + if (interfaceEnum.hasMoreElements()) { + ClassDoc interfaceDoc = (ClassDoc)interfaceEnum.nextElement(); + interfaceXML(interfaceDoc); + } + cm.endElement(xmlns, localName, "javadoc"); + } + + /** + * Generates doc for "package". + * <!ELEMENT package (doc?, package*, class*, interface*)> + *<!ATTLIST package + * name CDATA #REQUIRED> + */ + private void packageXML(PackageDoc packageDoc) throws SAXException { + AttributesImpl atts = new AttributesImpl(); + atts.addAttribute(xmlns, localName, "name", "String", packageDoc.name()); + cm.startElement(xmlns, localName, "package", atts); + + // generate Doc element. + docXML(packageDoc); + + // TODO:generate Package elements. + // doubt: How package can exist inside a package? + + /* Generate for classes. */ + // for ordinary classes. + ClassDoc[] classArray = packageDoc.ordinaryClasses(); + for (int i = 0; i < classArray.length; ++i) { + classXML(classArray[i]); + } + // for Exception classes. + classArray = packageDoc.exceptions(); + for (int i = 0; i < classArray.length; ++i) { + classXML(classArray[i]); + } + // for Error classes + classArray = packageDoc.errors(); + for (int i = 0; i < classArray.length; ++i) { + classXML(classArray[i]); + } + + /* Generate for interfaces. */ + ClassDoc[] interfaceArray = packageDoc.interfaces(); + for (int i = 0; i < interfaceArray.length; ++i) { + interfaceXML(interfaceArray[i]); + } + + cm.endElement(xmlns, localName, "package"); + } + + /** + * Generates doc for element "class". + * <!ELEMENT class (doc?, + * extends_class?, + * implements?, + * constructor*, + * method*, + * innerclass*)> + * <!ATTLIST class + * %name; + * %extensibility; + * %class.access;> + */ + private void classXML(ClassDoc classDoc) throws SAXException { + AttributesImpl atts = new AttributesImpl(); + atts.addAttribute(xmlns, localName, "name", "String", classDoc.name()); + + String extensibility = "default"; + if (classDoc.isAbstract()) { + extensibility = "abstract"; + } else if (classDoc.isFinal()) { + extensibility = "final"; + } + atts.addAttribute(xmlns, localName, "extensibility", "String", extensibility); + String access = "package"; + if (classDoc.isPublic()) { + access = "public"; + } + atts.addAttribute(xmlns, localName, "access", "String", access); + cm.startElement(xmlns, localName, "class", atts); + + // generate "doc" sub-element + docXML(classDoc); + + // generate "extends_class" sub-element + extendsXML(classDoc); + + // generate "implements" sub-element + implementsXML(classDoc); + + // generate "field" sub-elements + FieldDoc[] fieldArray = classDoc.fields(); + for (int i = 0; i < fieldArray.length; ++i) { + fieldXML(fieldArray[i]); + } + + // generate "constructor" sub-elements + ConstructorDoc[] constructorArray = classDoc.constructors(); + for (int i = 0; i < constructorArray.length; ++i) { + constructorXML(constructorArray[i]); + } + + // generate "method" sub-elements + MethodDoc[] methodArray = classDoc.methods(); + for (int i = 0; i < methodArray.length; ++i) { + methodXML(methodArray[i]); + } + + // generate "innerclass" sub-elements + ClassDoc[] innerClassArray = classDoc.innerClasses(); + for (int i = 0; i < innerClassArray.length; ++i) { + innerClassXML(innerClassArray[i]); + } + + cm.endElement(xmlns, localName, "class"); + } + + /** + * Generates doc for element "extends_class" + * <!ELEMENT extends_class (classref+)> + */ + private void extendsXML(ClassDoc classDoc) throws SAXException { + if (classDoc.superclass() != null) { + cm.startElement(xmlns, localName, "extends_class", emptyAtts); + createRefXML("classref", classDoc.superclass().qualifiedName()); + cm.endElement(xmlns, localName, "extends_class"); + } + } + + /** + * Generates doc for element "innerclass" + * <!ELEMENT innerclass (doc?, + * extends?, + * implements?, + * field*, + * constructor*, + * method*)> + * <!ATTLIST innerclass + * %name; + * %access; + * %abstract; + * %anonymous; + * %final; + * %static;> + */ + private void innerClassXML(ClassDoc classDoc) throws SAXException { + AttributesImpl atts = new AttributesImpl(); + atts.addAttribute(xmlns, localName, "name", "String", classDoc.name()); + String access = "package"; + if (classDoc.isPublic()) { + access = "public"; + } + atts.addAttribute(xmlns, localName, "access", "String", access); + atts.addAttribute(xmlns, localName, "abstract", "String", ""+ classDoc.isAbstract()); + String anonymous = "false"; + if (classDoc.name().equals("")) { + anonymous = "true"; + } + atts.addAttribute(xmlns, localName, "anonymous", "String", ""+ anonymous); + atts.addAttribute(xmlns, localName, "final", "String", ""+ "" + classDoc.isFinal()); + atts.addAttribute(xmlns, localName, "static", "String", ""+ "" + classDoc.isStatic()); + cm.startElement(xmlns, localName, "innerclass", atts); + + // generate "doc" sub-element + docXML(classDoc); + + // generate "extends" sub-element + extendsXML(classDoc); + + // generate "implements" sub-element + implementsXML(classDoc); + + // generate "field" sub-elements + FieldDoc[] fieldArray = classDoc.fields(); + for (int i = 0; i < fieldArray.length; ++i) { + fieldXML(fieldArray[i]); + } + + // generate "constructor" sub-elements + ConstructorDoc[] constructorArray = classDoc.constructors(); + for (int i = 0; i < constructorArray.length; ++i) { + constructorXML(constructorArray[i]); + } + + // generate "method" sub-elements + MethodDoc[] methodArray = classDoc.methods(); + for (int i = 0; i < methodArray.length; ++i) { + methodXML(methodArray[i]); + } + + cm.endElement(xmlns, localName,"innerclass"); + } + + /** + * Generates doc for element "interface" + * <!ELEMENT interface (doc?, + * extends_interface?, + * field*, + * method*)> + * <!ATTLIST interface + * %name; + * %access;> + */ + private void interfaceXML(ClassDoc interfaceDoc) throws SAXException { + AttributesImpl atts = new AttributesImpl(); + atts.addAttribute(xmlns, localName, "name", "String", interfaceDoc.name()); + String access = "package"; + if (interfaceDoc.isPublic()) { + access = "public"; + } + atts.addAttribute(xmlns, localName, "access", "String", access); + cm.startElement(xmlns, localName, "interface", atts); + + // generate "doc" sub-element + docXML(interfaceDoc); + + // generate "extends_interface" + extends_interfaceXML(interfaceDoc); + + // generate "field" sub-elements + FieldDoc[] fieldArray = interfaceDoc.fields(); + for (int i = 0; i < fieldArray.length; ++i) { + fieldXML(fieldArray[i]); + } + + // generate "method" sub-elements + MethodDoc[] methodArray = interfaceDoc.methods(); + for (int i = 0; i < methodArray.length; ++i) { + methodXML(methodArray[i]); + } + cm.endElement(xmlns, localName, "interface"); + } + + /** + * Generates doc for element "extends_interface" + * <!ELEMENT extends_interface (interfaceref+)> + */ + private void extends_interfaceXML(ClassDoc interfaceDoc) throws SAXException { + ClassDoc[] interfaceArray = interfaceDoc.interfaces(); + if (interfaceArray.length > 0) { + cm.startElement(xmlns, localName, "extends_interface", emptyAtts); + for (int i = 0; i < interfaceArray.length; ++i) { + createRefXML("interfaceref", interfaceArray[i].qualifiedName()); + } + cm.endElement(xmlns, localName, "extends_interface"); + } + } + + /** + * Generates doc for element "implements" + * <!ELEMENT implements (interfaceref+)> + */ + private void implementsXML(ClassDoc classDoc) throws SAXException { + ClassDoc[] interfaceArray = classDoc.interfaces(); + if (interfaceArray.length > 0) { + cm.startElement(xmlns, localName, "implements", emptyAtts); + for (int i = 0; i < interfaceArray.length; ++i) { + createRefXML("interfaceref", interfaceArray[i].qualifiedName()); + } + cm.endElement(xmlns, localName, "implements"); + } + if (classDoc.superclass() != null) { + implementsXML(classDoc.superclass()); + } + } + + /** + * Generates doc for element "throws" + * <!ELEMENT throws (classref)+> + */ + private void throwsXML(ExecutableMemberDoc member) throws SAXException { + ThrowsTag[] tagArray = member.throwsTags(); + if(tagArray.length > 0) { + cm.startElement(xmlns, localName, "throws", emptyAtts); + for (int i = 0; i < tagArray.length; ++i) { + ClassDoc exceptionClass = tagArray[i].exception(); + String name = null; + if (exceptionClass == null) { + name = tagArray[i].exceptionName(); + } else { + name = tagArray[i].exception().qualifiedName(); + } + createRefXML("classref", name); + } + cm.endElement(xmlns, localName, "throws"); + } + } + + /** + * Generates doc for following elements + * <!ELEMENT classref EMPTY> + * <!ATTLIST classref %name;> + * <!ELEMENT interfaceref EMPTY> + * <!ATTLIST interfaceref %name;> + * <!ELEMENT methodref EMPTY> + * <!ATTLIST methodref %name;> + * <!ELEMENT packageref EMPTY> + * <!ATTLIST packageref %name;> + */ + private void createRefXML(String elementName, String nameValue) throws SAXException { + AttributesImpl atts = new AttributesImpl(); + atts.addAttribute(xmlns, localName, "name", "String", nameValue); + cm.startElement(xmlns, localName, elementName, atts); + cm.endElement(xmlns, localName, elementName); + } + + /** + * Generates doc for "(classref|interfaceref|primitive)" sub-element + */ + private void createTypeRef(Type type) throws SAXException { + String qualifiedName = type.qualifiedTypeName(); + ClassDoc fieldType = type.asClassDoc(); + if (fieldType == null) { + // primitive data type + AttributesImpl subElmAtts = new AttributesImpl(); + subElmAtts.addAttribute(xmlns, localName, "type", "String", qualifiedName); + cm.startElement(xmlns, localName, "primitive", subElmAtts); + cm.endElement(xmlns, localName, "primitive"); + } else if (fieldType.isInterface()) { + // interface + createRefXML("interfaceref", qualifiedName); + } else { + // class + createRefXML("classref", qualifiedName); + } + } + + /** + * Generates doc for element "field" + * <!ELEMENT field (doc?, (classref | interfaceref | primitive))> + * <!ATTLIST field + * %name; + * %access; + * %dimension; + * %synthetic; + * %static; + * %final; + * %transient; + * %volatile;> + */ + private void fieldXML(FieldDoc field) throws SAXException { + AttributesImpl atts = new AttributesImpl(); + + atts.addAttribute(xmlns, localName, "name", "String", field.name()); + + String access = "package"; + if (field.isPrivate()) { + access = "private"; + } else if (field.isProtected()) { + access = "protected"; + } else if (field.isPublic()) { + access = "public"; + } + atts.addAttribute(xmlns, localName, "access", "String", access); + + atts.addAttribute(xmlns, localName, "dimension", "String", field.type().dimension()); + atts.addAttribute(xmlns, localName, "synthetic", "String", "" + field.isSynthetic()); + atts.addAttribute(xmlns, localName, "static", "String", "" + field.isStatic()); + atts.addAttribute(xmlns, localName, "final", "String", "" + field.isFinal()); + atts.addAttribute(xmlns, localName, "transient", "String", "" + field.isTransient()); + atts.addAttribute(xmlns, localName, "volatile", "String", "" + field.isVolatile()); + cm.startElement(xmlns, localName, "field", atts); + + // generate "doc" sub-element + docXML(field); + + // generate "(classref|interfaceref|primitive)" sub-element + createTypeRef(field.type()); // foo , field.qualifiedName()); + + cm.endElement(xmlns, localName, "field"); + } + + /** + * Generates doc for element "constructor" + * <!ELEMENT constructor (doc?, parameter*, throws*)> + * <!ATTLIST constructor + * %name; + * %access; + * %synthetic;> + */ + private void constructorXML(ConstructorDoc constrDoc) throws SAXException { + AttributesImpl atts = new AttributesImpl(); + atts.addAttribute(xmlns, localName, "name", "String", constrDoc.qualifiedName()); + String access = "package"; + if (constrDoc.isPrivate()) { + access = "private"; + } else if (constrDoc.isProtected()) { + access = "protected"; + } else if (constrDoc.isPublic()) { + access = "public"; + } + atts.addAttribute(xmlns, localName, "access", "String", access); + atts.addAttribute(xmlns, localName, "synthetic", "String", "" + constrDoc.isSynthetic()); + cm.startElement(xmlns, localName, "constructor", atts); + + // generate "doc" sub-element + docXML(constrDoc); + + // generate "parameter" sub-elements + Parameter[] parameterArray = constrDoc.parameters(); + for (int i = 0; i < parameterArray.length; ++i) { + parameterXML(parameterArray[i]); + } + + // generate "throws" sub-element + throwsXML(constrDoc); + + cm.endElement(xmlns, localName, "constructor"); + } + + /** + * Generates doc for element "method" + * <!ELEMENT method (doc?, returns, parameter*, throws*)> + * <!ATTLIST method + * %name; + * %access; + * %extensibility; + * %native; + * %synthetic; + * %static; + * %synchronized;> + */ + private void methodXML(MethodDoc methodDoc) throws SAXException { + AttributesImpl atts = new AttributesImpl(); + //atts.addAttribute(xmlns, localName, "", String, ); + atts.addAttribute(xmlns, localName, "name", "String", methodDoc.name()); + + String access = "package"; + if (methodDoc.isPrivate()) { + access = "private"; + } else if (methodDoc.isProtected()) { + access = "protected"; + } else if (methodDoc.isPublic()) { + access = "public"; + } + atts.addAttribute(xmlns, localName, "access", "String", access); + + String extensibility = "default"; + if (methodDoc.isAbstract()) { + extensibility = "abstract"; + } else if (methodDoc.isFinal()) { + extensibility = "final"; + } + atts.addAttribute(xmlns, localName, "extensiblity", "String", extensibility); + + atts.addAttribute(xmlns, localName, "native", "String", ""+ methodDoc.isNative()); + atts.addAttribute(xmlns, localName, "synthetic", "String", "" + methodDoc.isSynthetic()); + atts.addAttribute(xmlns, localName, "static", "String", "" + methodDoc.isStatic()); + atts.addAttribute(xmlns, localName, "synchronized", "String", ""+ methodDoc.isSynchronized()); + cm.startElement(xmlns, localName, "method", atts); + + // generate "doc" sub-element + docXML(methodDoc); + + // generate "returns" sub-element + returnsXML(methodDoc.returnType()); + + // generate "parameter" sub-elements + Parameter[] parameterArray = methodDoc.parameters(); + for (int i = 0; i < parameterArray.length; ++i) { + parameterXML(parameterArray[i]); + } + + // generate "throws" sub-element + throwsXML(methodDoc); + + cm.endElement(xmlns, localName, "method"); + } + + /** + * Generates doc for element "returns" + * <!ELEMENT returns (classref | interfaceref | primitive)> + * <!ATTLIST returns %dimension;> + */ + private void returnsXML(Type type) throws SAXException { + AttributesImpl atts = new AttributesImpl(); + atts.addAttribute(xmlns, localName, "dimension", "String", type.dimension()); + cm.startElement(xmlns, localName, "returns", atts); + + // generate "(classref|interfaceref|primitive)" sub-element + createTypeRef(type); + + cm.endElement(xmlns, localName, "returns"); + } + + /** + * Generates doc for element "parameter" + * <!ELEMENT parameter (classref | interfaceref | primitive)> + * <!ATTLIST parameter + * %name; + * %final; + * %dimension;> + */ + private void parameterXML(Parameter parameter) throws SAXException { + AttributesImpl atts = new AttributesImpl(); + atts.addAttribute(xmlns, localName, "name", "String", parameter.name()); + boolean isFinal = false; + Type type = parameter.type(); + if (type.asClassDoc() == null) { + isFinal = true; + } + atts.addAttribute(xmlns, localName, "final", "String", ""+ "" + isFinal); + atts.addAttribute(xmlns, localName, "dimension", "String", parameter.type().dimension()); + cm.startElement(xmlns, localName, "parameter", atts); + + // generate "(classref|interfaceref|primitive)" sub-element + createTypeRef(parameter.type()); + + cm.endElement(xmlns, localName,"parameter"); + } + + /** + * Generates doc for element "doc" + * <!ELEMENT doc (#PCDATA | + * linktag | + * authortag | + * versiontag | + * paramtag | + * returntag | + * exceptiontag | + * throwstag | + * seetag | + * sincetag | + * deprecatedtag | + * serialtag | + * serialfieldtag | + * serialdatatag)*> + */ + private void docXML(Doc doc) throws SAXException { + 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) { + tagXML(tags[i]); + } + cm.endElement(xmlns, localName, "doc"); + } + } + + /** + * Generates doc for all tag elements. + */ + private void tagXML(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 XMLDoclet(root); + return true; + } catch (Exception e) { + e.printStackTrace(); + System.exit(1); + return false; + } + } +} diff --git a/jellydoc/src/plugin-resources/maven-jellydoc-plugin.jelly b/jellydoc/src/plugin-resources/maven-jellydoc-plugin.jelly new file mode 100644 index 00000000..7cd209a0 --- /dev/null +++ b/jellydoc/src/plugin-resources/maven-jellydoc-plugin.jelly @@ -0,0 +1,163 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Tag Documentation + + + +
+ +

+ [tag libraries] + [tags] +

+

+ The following document contains a summary of all the core + Jelly tag libraries. +

+ +
+ +
+

+ [tag libraries] + [tags] +

+ + + + + + + + + + + + + +
LibraryDescription
${uri} + +
+ + + + + + + +

+ +

+ + + + + + + + + + + + + + + +
Tag NameDescription
${tagName} + +
+ + + + +
+ + + +
+

+ [tag libraries] + [tags] +

+ + + + + + + +

+ +

+ + + + + + + + + + + + + + + +
Attribute NameTypeDescription
+ +
+ + + + + + +
+ + + + + + + diff --git a/jellydoc/xdocs/.cvsignore b/jellydoc/xdocs/.cvsignore new file mode 100644 index 00000000..cb6131bb --- /dev/null +++ b/jellydoc/xdocs/.cvsignore @@ -0,0 +1 @@ +stylesheets diff --git a/jellydoc/xdocs/goals.xml b/jellydoc/xdocs/goals.xml new file mode 100644 index 00000000..21f07cfb --- /dev/null +++ b/jellydoc/xdocs/goals.xml @@ -0,0 +1,27 @@ + + + + + JellyDoc Plugin Goals + James Strachan + + + +
+ + + + + + + + + +
GoalDescription
jellydoc + The default goal. This goal generates the JellyDoc documentation of + all Jelly tags defined within your code base which can then be styled + into HTML as part of the xdoc goal +
+
+ + diff --git a/jellydoc/xdocs/index.xml b/jellydoc/xdocs/index.xml new file mode 100644 index 00000000..cee9619c --- /dev/null +++ b/jellydoc/xdocs/index.xml @@ -0,0 +1,22 @@ + + + + + Maven JellyDoc Plug-in + James Strachan + + + +
+

+ This plug-in provides JellyDoc reporting documenting all the Jelly + Tags defined in your code base using the + jellydoc goal as described here. +

+

+ The properties that allow you to customize the execution + are documented here. +

+
+ + diff --git a/jellydoc/xdocs/navigation.xml b/jellydoc/xdocs/navigation.xml new file mode 100644 index 00000000..dc3ded21 --- /dev/null +++ b/jellydoc/xdocs/navigation.xml @@ -0,0 +1,16 @@ + + + + Maven JellyDoc Plugin + + + + + + + + + + + + diff --git a/jellydoc/xdocs/properties.xml b/jellydoc/xdocs/properties.xml new file mode 100644 index 00000000..e6b178a9 --- /dev/null +++ b/jellydoc/xdocs/properties.xml @@ -0,0 +1,26 @@ + + + + + JellyDoc Properties + James Strachan + + + +
+ + + + + + + +
PropertyOptional?Description
maven.jellydoc.packagesYes + Specifies the packages which contain Jelly tags. + By restricting this to a subset of your packages will optimise the + goal and simplify the documentation. e.g. setting it to org.foo.jelly.* + The default value is ${pom.build.sourceDirectory}.* +
+
+ +