diff options
Diffstat (limited to 'src/taskdocs')
| -rw-r--r-- | src/taskdocs/java/net/sf/antcontrib/taskdocs/TaskDoclet.java | 1 | ||||
| -rw-r--r-- | src/taskdocs/resources/net/sf/antcontrib/taskdocs/element.xslt | 210 |
2 files changed, 211 insertions, 0 deletions
diff --git a/src/taskdocs/java/net/sf/antcontrib/taskdocs/TaskDoclet.java b/src/taskdocs/java/net/sf/antcontrib/taskdocs/TaskDoclet.java new file mode 100644 index 0000000..8d22928 --- /dev/null +++ b/src/taskdocs/java/net/sf/antcontrib/taskdocs/TaskDoclet.java @@ -0,0 +1 @@ +/*
Licensed to the Ant-Contrib Project under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The Ant-Contrib Project licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package net.sf.antcontrib.taskdocs;
import com.sun.javadoc.*;
import org.xml.sax.*;
import org.xml.sax.helpers.AttributesImpl;
import org.xml.sax.helpers.DefaultHandler;
import javax.xml.parsers.SAXParser;
import javax.xml.parsers.SAXParserFactory;
import javax.xml.transform.Source;
import javax.xml.transform.sax.SAXTransformerFactory;
import javax.xml.transform.sax.TransformerHandler;
import javax.xml.transform.stream.StreamResult;
import javax.xml.transform.stream.StreamSource;
import java.io.File;
import java.io.StringReader;
import java.util.HashMap;
import java.util.Iterator;
import java.util.Locale;
import java.util.Map;
/**
* This document writes an XML representation of the
* Ant related Javadoc through an XSLT transform that creates xdoc files.
*
*/
public final class TaskDoclet {
/**
* Process Javadoc content.
* @param root root of javadoc content.
* @return true if successful
* @throws Exception IO exceptions and the like.
*/
public static boolean start(RootDoc root) throws Exception {
SAXTransformerFactory tf = (SAXTransformerFactory) SAXTransformerFactory.newInstance();
Source typeStyle = new StreamSource(new File("src/taskdocs/resources/net/sf/antcontrib/taskdocs/element.xslt"));
//
// replace with tf.newTransformerHandler() if you want to see raw generated XML.
TransformerHandler typeHandler = tf.newTransformerHandler(typeStyle);
Map referencedTypes = new HashMap();
Map documentedTypes = new HashMap();
ClassDoc[] classes = root.classes();
for (int i = 0; i < classes.length; ++i) {
ClassDoc clazz = classes[i];
if (clazz.isPublic() && !clazz.isAbstract()) {
if (isTask(clazz) || isType(clazz)) {
writeClass(typeHandler, clazz, referencedTypes);
documentedTypes.put(clazz.qualifiedTypeName(), clazz);
}
}
}
Map additionalTypes = new HashMap();
for (Iterator iter = referencedTypes.keySet().iterator(); iter.hasNext();) {
String referencedName = (String) iter.next();
if (documentedTypes.get(referencedName) == null) {
ClassDoc referencedClass = root.classNamed(referencedName);
if (referencedClass != null) {
if (!referencedClass.qualifiedTypeName().startsWith("org.apache.tools.ant")) {
writeClass(typeHandler, referencedClass, additionalTypes);
documentedTypes.put(referencedClass.qualifiedTypeName(), referencedClass);
}
}
}
}
return true;
}
/**
* Determine if class is an Ant task.
* @param clazz class to test.
* @return true if class is an Ant task.
*/
private static boolean isTask(final ClassDoc clazz) {
if (clazz == null) return false;
if ("org.apache.tools.ant.Task".equals(clazz.qualifiedTypeName())) {
System.out.print("true");
return true;
}
return isTask(clazz.superclass());
}
/**
* Determine if class is an Ant type.
* @param clazz class to test.
* @return true if class is an Ant type.
*/
private static boolean isType(final ClassDoc clazz) {
if (clazz == null) return false;
if ("org.apache.tools.ant.types.DataType".equals(clazz.qualifiedTypeName())) {
return true;
}
return isType(clazz.superclass());
}
/**
* Namespace URI for class description elements.
*/
private static final String NS_URI = "http://ant-contrib.sf.net/taskdocs";
/**
* Namespace URI for XHTML elements.
*/
private static final String XHTML_URI = "http://www.w3.org/1999/xhtml";
/**
* Write a Java type.
* @param tf content handler.
* @param type documented type.
* @throws Exception if IO or other exception.
*/
private static void writeType(final TransformerHandler tf, final Type type) throws Exception {
AttributesImpl attributes = new AttributesImpl();
attributes.addAttribute(null, "name", "name", "CDATA", type.simpleTypeName());
attributes.addAttribute(null, "qualifiedTypeName", "qualifiedTypeName", "CDATA", type.qualifiedTypeName());
tf.startElement(NS_URI, "type", "type", attributes);
ClassDoc typeDoc = type.asClassDoc();
if (typeDoc != null && typeDoc.commentText() != null && typeDoc.commentText().length() > 0) {
writeDescription(tf, typeDoc.commentText());
} else {
tf.characters(type.typeName().toCharArray(), 0, type.typeName().length());
}
tf.endElement(NS_URI, "type", "type");
}
/**
* Write an Ant task or type attribute (aka property).
* @param tf content handler.
* @param method set method for property.
* @throws Exception if IO or other exception.
*/
private static void writeAttribute(final TransformerHandler tf, final MethodDoc method) throws Exception {
AttributesImpl attributes = new AttributesImpl();
attributes.addAttribute(null, "name", "name", "CDATA", method.name().substring(3).toLowerCase(Locale.US));
tf.startElement(NS_URI, "attribute", "attribute", attributes);
writeType(tf, method.parameters()[0].type());
attributes.clear();
tf.startElement(NS_URI, "comment", "comment", attributes);
writeDescription(tf, method.commentText());
tf.endElement(NS_URI, "comment", "comment");
tf.endElement(NS_URI, "attribute", "attribute");
}
/**
* Write an Ant nested element.
* @param tf content handler.
* @param method method to add element to task or type.
* @param name name of nested element.
* @param type type of nested element.
* @param referencedTypes map of types referenced in documentation.
* @throws Exception if IO or other exception.
*/
private static void writeChild(final TransformerHandler tf,
final MethodDoc method,
final String name,
final Type type,
final Map referencedTypes) throws Exception {
AttributesImpl attributes = new AttributesImpl();
attributes.addAttribute(null, "name", "name", "CDATA", name.toLowerCase(Locale.US));
tf.startElement(NS_URI, "child", "child", attributes);
attributes.clear();
tf.startElement(NS_URI, "comment", "comment", attributes);
writeDescription(tf, method.commentText());
tf.endElement(NS_URI, "comment", "comment");
writeType(tf, type);
tf.endElement(NS_URI, "child", "child");
referencedTypes.put(type.qualifiedTypeName(), type);
}
/**
* Redirects parsed XHTML comment into output stream.
* Drops start and end document and body element.
*/
private static class RedirectHandler extends DefaultHandler {
/**
* output handler.
*/
private final ContentHandler tf;
/**
* Create new instance.
* @param tf output handler, may not be null.
*/
public RedirectHandler(final TransformerHandler tf) {
if (tf == null) { throw new IllegalArgumentException("tf"); }
this.tf = tf;
}
/** {@inheritDoc} */
public void characters(final char[] ch, final int start, final int length) throws SAXException {
tf.characters(ch, start, length);
}
/** {@inheritDoc} */
public void endDocument() {
}
/** {@inheritDoc} */
public void endElement(final String namespaceURI,
final String localName,
final String qName) throws SAXException {
if (!"body".equals(localName)) {
tf.endElement(namespaceURI, localName, qName);
}
}
/** {@inheritDoc} */
public void endPrefixMapping(final String prefix) throws SAXException {
tf.endPrefixMapping(prefix);
}
/** {@inheritDoc} */
public void ignorableWhitespace(char[] ch, int start, int length) throws SAXException {
tf.ignorableWhitespace(ch, start, length);
}
/** {@inheritDoc} */
public void processingInstruction(final String target, final String data) throws SAXException {
tf.processingInstruction(target, data);
}
/** {@inheritDoc} */
public void setDocumentLocator(final Locator locator) {
tf.setDocumentLocator(locator);
}
/** {@inheritDoc} */
public void skippedEntity(String name) throws SAXException {
tf.skippedEntity(name);
}
/** {@inheritDoc} */
public void startDocument() {
}
/** {@inheritDoc} */
public void startElement(final String namespaceURI,
final String localName,
final String qName,
final Attributes atts) throws SAXException {
if (!"body".equals(localName)) {
tf.startElement(namespaceURI, localName, qName, atts);
}
}
/** {@inheritDoc} */
public void startPrefixMapping(String prefix, String uri) throws SAXException {
tf.startPrefixMapping(prefix, uri);
}
}
/**
* Writes description.
* @param tf destination.
* @param description description, may contain XHTML elements.
* @throws SAXException if IO or other exception.
*/
private static void writeDescription(final TransformerHandler tf,
final String description) throws SAXException {
if (description.indexOf('<') == -1) {
tf.characters(description.toCharArray(), 0, description.length());
} else {
//
// attempt to fabricate an XHTML fragment
//
StringBuffer buf = new StringBuffer(description);
buf.insert(0, "<body xmlns='" + XHTML_URI + "'>");
buf.append("</body>");
try {
SAXParserFactory sf = SAXParserFactory.newInstance();
sf.setNamespaceAware(true);
SAXParser parser = sf.newSAXParser();
parser.parse(new InputSource(new StringReader(buf.toString())), new RedirectHandler(tf));
} catch (Exception ex) {
tf.characters(ex.toString().toCharArray(), 0, ex.toString().length());
}
}
}
/**
* Write all Ant attributes in this class and superclasses.
* @param tf destination.
* @param clazz class documentation.
* @param processed map of processed methods.
* @param referencedTypes map of referenced types.
* @throws Exception if IO or other exception.
*/
private static void writeAttributes(final TransformerHandler tf,
final ClassDoc clazz,
final Map processed,
final Map referencedTypes) throws Exception {
MethodDoc[] methods = clazz.methods();
for (int i = 0; i < methods.length; i++) {
MethodDoc method = methods[i];
if (processed.get(method.name()) == null) {
if (method.name().startsWith("set") && method.isPublic() && method.parameters().length == 1) {
writeAttribute(tf, method);
referencedTypes.put(method.parameters()[0].typeName(), method.parameters()[0].type());
}
processed.put(method.name(), method);
}
}
if (clazz.superclass() != null) {
writeAttributes(tf, clazz.superclass(), processed, referencedTypes);
}
}
/**
* Write all Ant nested elements in this class and superclasses.
* @param tf destination.
* @param clazz class documentation.
* @param processed map of processed methods.
* @param referencedTypes map of referenced types.
* @throws Exception if IO or other exception.
*/
private static final void writeChildren(final TransformerHandler tf,
final ClassDoc clazz,
final Map processed,
final Map referencedTypes) throws Exception {
MethodDoc[] methods = clazz.methods();
for (int i = 0; i < methods.length; i++) {
MethodDoc method = methods[i];
if (processed.get(method.name()) == null) {
if (method.name().startsWith("addConfigured") && method.isPublic() && method.parameters().length == 1) {
writeChild(tf, method, method.name().substring(13), method.parameters()[0].type(), referencedTypes);
} else if (method.name().startsWith("add") && method.isPublic() && method.parameters().length == 1) {
writeChild(tf, method, method.name().substring(3), method.parameters()[0].type(), referencedTypes);
} else if (method.isPublic() && method.parameters().length == 0 && method.name().startsWith("create")) {
writeChild(tf, method, method.name().substring(6), method.returnType(), referencedTypes);
}
processed.put(method.name(), method);
}
}
if (clazz.superclass() != null) {
writeChildren(tf, clazz.superclass(), processed, referencedTypes);
}
}
/**
* Write Ant documentation for this class.
* @param tf destination.
* @param clazz class documentation.
* @param referencedTypes map of referenced types.
* @throws Exception if IO or other exception.
*/
private static void writeClass(final TransformerHandler tf,
final ClassDoc clazz,
final Map referencedTypes) throws Exception {
StreamResult result = new StreamResult(new File("src/site/xdoc/antdocs/" + clazz.name() + ".xml"));
tf.setResult(result);
AttributesImpl attributes = new AttributesImpl();
attributes.addAttribute(null, "name", "name", "CDATA", clazz.name());
StringBuffer firstSentence = new StringBuffer();
Tag[] tags = clazz.firstSentenceTags();
for (int i = 0; i < tags.length; i++) {
firstSentence.append(tags[i].text());
}
if (firstSentence.length() > 0) {
attributes.addAttribute(null, "firstSentence", "firstSentence", "CDATA", firstSentence.toString());
}
tf.startDocument();
tf.startElement(NS_URI, "class", "class", attributes);
attributes.clear();
tf.startElement(NS_URI, "comment", "comment", attributes);
writeDescription(tf, clazz.commentText());
tf.endElement(NS_URI, "comment", "comment");
tf.startElement(NS_URI, "attributes", "attributes", attributes);
Map methods = new HashMap();
methods.put("setProject", "setProject");
methods.put("setRuntimeConfigurableWrapper", "setRuntimeConfigurableWrapper");
writeAttributes(tf, clazz, methods, referencedTypes);
tf.endElement(NS_URI, "attributes", "attributes");
tf.startElement(NS_URI, "children", "children", attributes);
Map children = new HashMap();
writeChildren(tf, clazz, children, referencedTypes);
tf.endElement(NS_URI, "children", "children");
tf.endElement(NS_URI, "class", "class");
tf.endDocument();
}
}
\ No newline at end of file diff --git a/src/taskdocs/resources/net/sf/antcontrib/taskdocs/element.xslt b/src/taskdocs/resources/net/sf/antcontrib/taskdocs/element.xslt new file mode 100644 index 0000000..b489247 --- /dev/null +++ b/src/taskdocs/resources/net/sf/antcontrib/taskdocs/element.xslt @@ -0,0 +1,210 @@ +<!-- + Licensed to the Ant-Contrib Project under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The Ant-Contrib Project licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +--> +<xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:taskdocs="http://ant-contrib.sf.net/taskdocs" + xmlns:xhtml="http://www.w3.org/1999/xhtml" + xsl:version="1.0"> + + <xsl:output method="xml" indent="yes"/> + + <xsl:apply-templates select="/"/> + + <xsl:template match="/"> + + <xsl:comment> + +Licensed to the Ant-Contrib Project under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The Ant-Contrib Project licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + </xsl:comment> + <document> + <xsl:apply-templates/> + </document> +</xsl:template> + + <xsl:template match="xhtml:*"> + <xsl:element name="{local-name()}"> + <xsl:apply-templates/> + </xsl:element> + </xsl:template> + + <xsl:template match="text()"> + <xsl:value-of select="."/> + </xsl:template> + + <xsl:template name="pretty-name"> + <xsl:param name="name"/> + <xsl:choose> + <xsl:when test="contains($name, 'SystemLibrarySet')">syslibset</xsl:when> + <xsl:when test="contains($name, 'LibrarySet')">libset</xsl:when> + <xsl:when test="contains($name, 'TargetDef')">targetplatform</xsl:when> + <xsl:when test="string-length(substring-before($name, 'Task'))"> + <xsl:call-template name="pretty-name"> + <xsl:with-param name="name"> + <xsl:value-of select="substring-before($name, 'Task')"/> + </xsl:with-param> + </xsl:call-template> + </xsl:when> + <xsl:when test="string-length(substring-before($name, 'Def'))"> + <xsl:call-template name="pretty-name"> + <xsl:with-param name="name"> + <xsl:value-of select="substring-before($name, 'Def')"/> + </xsl:with-param> + </xsl:call-template> + </xsl:when> + <xsl:when test="string-length(substring-before($name, 'Argument'))"> + <xsl:call-template name="pretty-name"> + <xsl:with-param name="name"> + <xsl:value-of select="substring-before($name, 'ument')"/> + </xsl:with-param> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="translate($name, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')"/> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <xsl:template match="taskdocs:class"> + <properties> + <title> + <xsl:call-template name='pretty-name'> + <xsl:with-param name="name"> + <xsl:value-of select="@name"/> + </xsl:with-param> + </xsl:call-template> + </title> + </properties> + <body> + + <section> + <xsl:attribute name="name"> + <xsl:call-template name='pretty-name'> + <xsl:with-param name="name"> + <xsl:value-of select="@name"/> + </xsl:with-param> + </xsl:call-template> + </xsl:attribute> + <subsection name="Description"> + <xsl:apply-templates select="taskdocs:comment"/> + </subsection> + <xsl:if test="taskdocs:attributes/taskdocs:attribute"> + <subsection name="parameters"> + <table> + <tr> + <td><b>Attribute</b></td> + <td><b>Description</b></td> + <td><b>Type</b></td> + </tr> + <xsl:apply-templates select="taskdocs:attributes/taskdocs:attribute"> + <xsl:sort select="@name"/> + </xsl:apply-templates> + </table> + </subsection> + </xsl:if> + <xsl:if test="taskdocs:children/taskdocs:child"> + <subsection name="parameters as nested elements"> + <dl> + <xsl:apply-templates select="taskdocs:children/taskdocs:child"> + <xsl:sort select="@name"/> + </xsl:apply-templates> + </dl> + + </subsection> + </xsl:if> + </section> + </body> + + </xsl:template> + + <xsl:template match="taskdocs:attribute"> + <tr> + <td> + <xsl:value-of select="@name"/> + </td> + <td> + <xsl:apply-templates select="taskdocs:comment"/> + </td> + <td> + <xsl:for-each select="taskdocs:type"> + <xsl:call-template name="attribute-type"/> + </xsl:for-each> + </td> + </tr> + + </xsl:template> + + <xsl:template name="attribute-type"> + <xsl:choose> + <xsl:when test="starts-with(@qualifiedTypeName, 'net.sf.antcontrib.cpptasks.')"> + <a href="../apidocs/{translate(@qualifiedTypeName, '.', '/')}.html"> + <xsl:value-of select="@name"/> + </a> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="@name"/> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <xsl:template name="child-type"> + <xsl:param name="anchor"><xsl:value-of select="@name"/></xsl:param> + <xsl:element name="a"> + <xsl:attribute name="href"> + <xsl:choose> + <xsl:when test="starts-with(@qualifiedTypeName, 'net.sf.antcontrib.cpptasks')"><xsl:value-of select="@name"/>.html</xsl:when> + <xsl:when test="starts-with(@qualifiedTypeName, 'org.apache.tools.ant.types.PatternSet')">http://ant.apache.org/manual/CoreTypes/patternset.html</xsl:when> + <xsl:when test="starts-with(@qualifiedTypeName, 'org.apache.tools.ant.types.Path')">http://ant.apache.org/manual/using.html#path</xsl:when> + <xsl:when test="starts-with(@qualifiedTypeName, 'org.apache.tools.ant.types.Commandline')">http://ant.apache.org/manual/CoreTasks/exec.html</xsl:when> + <xsl:otherwise>about:blank</xsl:otherwise> + </xsl:choose> + </xsl:attribute> + <xsl:value-of select="$anchor"/> + </xsl:element> + </xsl:template> + + <xsl:template match="taskdocs:child"> + <dt> + <xsl:variable name="anchor"> + <xsl:value-of select="@name"/> + </xsl:variable> + <xsl:for-each select="taskdocs:type"> + <xsl:call-template name="child-type"> + <xsl:with-param name="anchor"> + <xsl:value-of select="$anchor"/> + </xsl:with-param> + </xsl:call-template> + </xsl:for-each> + </dt> + <dd><xsl:value-of select="taskdocs:comment"/></dd> + </xsl:template> + + +</xsl:transform> |