Author: mrdon
Date: Wed Feb 23 18:05:12 2005
New Revision: 155135
URL: http://svn.apache.org/viewcvs?view=rev&rev=155135
Log:
* Adding XDoclet-based Java API extension documentation system
* Adding Javadocs to Java API extension classes
Added:
struts/flow/trunk/src/doc/
struts/flow/trunk/src/doc/extensions.xdt
Modified:
struts/flow/trunk/build.xml
struts/flow/trunk/project.xml
struts/flow/trunk/src/java/org/apache/struts/flow/sugar/CollectionExtensions.java
struts/flow/trunk/src/java/org/apache/struts/flow/sugar/FileExtensions.java
struts/flow/trunk/src/java/org/apache/struts/flow/sugar/ListExtensions.java
Modified: struts/flow/trunk/build.xml
URL:
http://svn.apache.org/viewcvs/struts/flow/trunk/build.xml?view=diff&r1=155134&r2=155135
==============================================================================
--- struts/flow/trunk/build.xml (original)
+++ struts/flow/trunk/build.xml Wed Feb 23 18:05:12 2005
@@ -31,15 +31,17 @@
<property name="src.dir" value="src" />
<property name="src.java" value="${src.dir}/java" />
<property name="src.test" value="${src.dir}/test" />
+ <property name="src.doc" value="${src.dir}/doc" />
<property name="src.guess.example" value="${src.dir}/guess-example" />
<property name="src.wizard.example" value="${src.dir}/wizard-example" />
- <property name="build.dir" value="build" />
+ <property name="build.dir" value="ant-build" />
<property name="build.guess.example" value="${build.dir}/guess-example" />
<property name="build.wizard.example" value="${build.dir}/wizard-example"
/>
<property name="build.target" value="${build.dir}/target" />
<property name="build.test" value="${build.dir}/test" />
+ <property name="build.doc" value="${build.dir}/doc" />
<property name="javadoc.packages" value="org.apache.struts.flow.*" />
@@ -80,6 +82,16 @@
<get dest="${lib.build}/servletapi-2.3.jar" usetimestamp="true"
ignoreerrors="true"
src="http://www.ibiblio.org/maven/servletapi/jars/servletapi-2.3.jar"/>
+ <get dest="${lib.build}/xdoclet-1.2.jar" usetimestamp="true"
+ ignoreerrors="true"
+
src="http://www.ibiblio.org/maven/xdoclet/jars/xdoclet-1.2.jar"/>
+ <get dest="${lib.build}/xjavadoc-1.0.3.jar" usetimestamp="true"
+ ignoreerrors="true"
+
src="http://www.ibiblio.org/maven/xdoclet/jars/xjavadoc-1.0.3.jar"/>
+ <get dest="${lib.core}/commons-collections-2.0.jar"
usetimestamp="true"
+ ignoreerrors="true"
+
src="http://www.ibiblio.org/maven/commons-collections/jars/commons-collections-2.0.jar"/>
+
<mkdir dir="${lib.core}" />
<get dest="${lib.core}/struts-1.1.jar" usetimestamp="true"
@@ -112,7 +124,7 @@
<get dest="${lib.core}/commons-digester.jar" usetimestamp="true"
ignoreerrors="true"
src="http://www.ibiblio.org/maven/commons-digester/jars/commons-digester-1.6.jar"/>
- </target>
+ </target>
<!--
@@ -128,6 +140,18 @@
<delete dir="${doc.dir}" />
</target>
+ <target name="doc.extensions" depends="prepare">
+ <delete dir="${build.doc}"/>
+ <taskdef name="doclet"
+ classname="xdoclet.DocletTask"
+ classpathref="base.classpath"/>
+
+ <doclet destdir="${build.doc}" verbose="true">
+ <fileset dir="${src.java}" includes="**/*Extensions.java"/>
+ <template templateFile="${src.doc}/extensions.xdt"
destinationFile="extensions.html"/>
+ </doclet>
+ </target>
+
<!--
The "prepare" target creates a directory structure in the build
target
area for the unpacked files associated with this web application
Modified: struts/flow/trunk/project.xml
URL:
http://svn.apache.org/viewcvs/struts/flow/trunk/project.xml?view=diff&r1=155134&r2=155135
==============================================================================
--- struts/flow/trunk/project.xml (original)
+++ struts/flow/trunk/project.xml Wed Feb 23 18:05:12 2005
@@ -112,6 +112,20 @@
<id>oro</id>
<version>2.0.7</version>
</dependency>
+ <dependency>
+ <id>xdoclet</id>
+ <version>1.2</version>
+ </dependency>
+ <dependency>
+ <id>xdoclet</id>
+ <artifactId>xjavadoc</artifactId>
+ <version>1.0.3</version>
+ </dependency>
+ <dependency>
+ <id>commons-collections</id>
+ <version>2.0</version>
+ </dependency>
+
</dependencies>
<build>
Added: struts/flow/trunk/src/doc/extensions.xdt
URL:
http://svn.apache.org/viewcvs/struts/flow/trunk/src/doc/extensions.xdt?view=auto&rev=155135
==============================================================================
--- struts/flow/trunk/src/doc/extensions.xdt (added)
+++ struts/flow/trunk/src/doc/extensions.xdt Wed Feb 23 18:05:12 2005
@@ -0,0 +1,89 @@
+<html>
+<head>
+ <title>Java API Extensions</title>
+</head>
+<body>
+<h2>Java API Extensions</h2>
+<p>
+The following are methods that are added to Java API classes to
+make developing with Struts Flow easier.
+</p>
+<XDtClass:forAllClasses>
+ <XDtClass:ifHasClassTag tagName="targetClass">
+ <h3><XDtClass:classTagValue tagName="targetClass" /></h3>
+ <table width="100%" border="1">
+ <XDtMethod:forAllMethods>
+ <XDtMethod:ifIsPublic>
+ <XDtMethod:ifHasMethodTag tagName="propReturn">
+ <tr>
+ <td><small><XDtMethod:methodTagValue tagName="propReturn"
/></small></td>
+ <td><a href="#<XDtClass:className />_<XDtMethod:methodName
/>"><XDtMethod:methodName /></a> -
<XDtMethod:firstSentenceDescriptionOfCurrentMethod /></td>
+ </tr>
+ </XDtMethod:ifHasMethodTag>
+ </XDtMethod:ifIsPublic>
+ </XDtMethod:forAllMethods>
+ </table>
+ <br />
+ <table width="100%" border="1">
+ <XDtMethod:forAllMethods>
+ <XDtMethod:ifIsPublic>
+ <XDtMethod:ifHasMethodTag tagName="funcReturn">
+ <tr>
+ <td><small><XDtMethod:methodTagValue tagName="funcReturn"
/></small></td>
+ <td><a href="#<XDtClass:className />_<XDtMethod:methodName
/>"><XDtMethod:methodName />(<XDtMethod:methodTagValue tagName="funcParams"
/>)</a> - <XDtMethod:firstSentenceDescriptionOfCurrentMethod /></td>
+ </tr>
+ </XDtMethod:ifHasMethodTag>
+ </XDtMethod:ifIsPublic>
+ </XDtMethod:forAllMethods>
+ </table>
+ </XDtClass:ifHasClassTag>
+</XDtClass:forAllClasses>
+<hr />
+<XDtClass:forAllClasses>
+ <XDtClass:ifHasClassTag tagName="targetClass">
+ <h3><XDtClass:classTagValue tagName="targetClass" /></h3>
+ <XDtMethod:forAllMethods>
+ <XDtMethod:ifIsPublic>
+ <XDtMethod:ifHasMethodTag tagName="propReturn">
+ <hr />
+ <a name="<XDtClass:className />_<XDtMethod:methodName />" />
+ <h4><XDtMethod:methodName /></h4>
+ <code><XDtMethod:methodTagValue tagName="funcReturn" />
<XDtMethod:methodName /></code>
+ <blockquote>
+ <p>
+ <XDtMethod:methodComment no-comment-signs="true"/>
+ </p>
+ <p>
+ <strong>Example(s):</strong><br />
+ <code><XDtMethod:methodTagValue tagName="example" /></code>
+ </p>
+ </blockquote>
+ </XDtMethod:ifHasMethodTag>
+ </XDtMethod:ifIsPublic>
+ </XDtMethod:forAllMethods>
+ <XDtMethod:forAllMethods>
+ <XDtMethod:ifIsPublic>
+ <XDtMethod:ifHasMethodTag tagName="funcReturn">
+ <hr />
+ <a name="<XDtClass:className />_<XDtMethod:methodName />" />
+ <h4><XDtMethod:methodName /></h4>
+
+ <code><XDtMethod:methodTagValue tagName="funcReturn" />
<XDtMethod:methodName />(<XDtMethod:methodTagValue tagName="funcParams"
/>)</code>
+ <blockquote>
+ <p>
+ <XDtMethod:methodComment no-comment-signs="true"/>
+ </p>
+ <p>
+ <strong>Example(s):</strong><br />
+ <code><XDtMethod:methodTagValue tagName="example" /></code>
+ </p>
+ </blockquote>
+ </XDtMethod:ifHasMethodTag>
+ </XDtMethod:ifIsPublic>
+ </XDtMethod:forAllMethods>
+ </XDtClass:ifHasClassTag>
+</XDtClass:forAllClasses>
+
+
+</body>
+</html>
Modified:
struts/flow/trunk/src/java/org/apache/struts/flow/sugar/CollectionExtensions.java
URL:
http://svn.apache.org/viewcvs/struts/flow/trunk/src/java/org/apache/struts/flow/sugar/CollectionExtensions.java?view=diff&r1=155134&r2=155135
==============================================================================
---
struts/flow/trunk/src/java/org/apache/struts/flow/sugar/CollectionExtensions.java
(original)
+++
struts/flow/trunk/src/java/org/apache/struts/flow/sugar/CollectionExtensions.java
Wed Feb 23 18:05:12 2005
@@ -22,9 +22,20 @@
/**
* Adds various function extensions to java.util.List implementations.
+ *
+ * @targetClass java.util.Collection
*/
public class CollectionExtensions {
+ /**
+ * Iterates through the collection and for each element,
+ * calls the passed function with the element as the
+ * parameter.
+ *
+ * @funcParams Function func
+ * @funcReturn void
+ * @example list.each(function(item) { print(item) })
+ */
public static ExtensionFunction each(final Collection col) {
return new ExtensionFunction() {
public Object execute(Context cx, Scriptable scope, Scriptable
thisObj, java.lang.Object[] args) {
@@ -39,7 +50,16 @@
}
};
}
-
+
+ /**
+ * Finds the first item selected by the passed function. The function
+ * will receive the item and should return true or false for the
+ * result.
+ *
+ * @funcParams Function func
+ * @funcReturn Object
+ * @example item = list.find(function(item) { return
item.matches(/foo[0-9]/) })
+ */
public static ExtensionFunction find(final Collection col) {
return new ExtensionFunction() {
public Object execute(Context cx, Scriptable scope, Scriptable
thisObj, java.lang.Object[] args) {
@@ -58,6 +78,15 @@
};
}
+ /**
+ * Finds all items selected by the passed function. The function
+ * will receive the item and should return true or false for the
+ * result. A list of all matches will be returned.
+ *
+ * @funcParams Function func
+ * @funcReturn java.util.List
+ * @example matches = list.findAll(function(item) { return
item.matches(/foo[0-9]/) })
+ */
public static ExtensionFunction findAll(final Collection col) {
return new ExtensionFunction() {
public Object execute(Context cx, Scriptable scope, Scriptable
thisObj, java.lang.Object[] args) {
@@ -77,6 +106,14 @@
};
}
+ /**
+ * Provides the current size of the collection. Alternative to
+ * the size() method to be more consistent with Javascript
+ * arrays.
+ *
+ * @propReturn int
+ * @example list.length
+ */
public static int length(Collection col, Scriptable scope) {
return col.size();
}
Modified:
struts/flow/trunk/src/java/org/apache/struts/flow/sugar/FileExtensions.java
URL:
http://svn.apache.org/viewcvs/struts/flow/trunk/src/java/org/apache/struts/flow/sugar/FileExtensions.java?view=diff&r1=155134&r2=155135
==============================================================================
--- struts/flow/trunk/src/java/org/apache/struts/flow/sugar/FileExtensions.java
(original)
+++ struts/flow/trunk/src/java/org/apache/struts/flow/sugar/FileExtensions.java
Wed Feb 23 18:05:12 2005
@@ -22,9 +22,18 @@
/**
* Adds various functions to java.io.File
+ * @targetClass java.io.File
*/
public class FileExtensions {
+
+ /**
+ * Appends text to the file.
+ *
+ * @funcParams String text
+ * @funcReturn java.io.File
+ * @example file.append("added text")
+ */
public static ExtensionFunction append(final File file) {
return new ExtensionFunction() {
public Object execute(Context cx, Scriptable scope, Scriptable
thisObj, java.lang.Object[] args)
@@ -38,6 +47,13 @@
};
}
+ /**
+ * Gets the contents of the file as a String.
+ *
+ * @funcParams
+ * @funcReturn String
+ * @example text = file.getText()
+ */
public static ExtensionFunction getText(final File file) {
return new ExtensionFunction() {
public Object execute(Context cx, Scriptable scope, Scriptable
thisObj, java.lang.Object[] args)
@@ -58,6 +74,15 @@
};
}
+ /**
+ * Passes each line to the provided function. The file is opened, and
+ * interpreted as a text file using the default encoding. Each line
+ * is read and passed to the provided function.
+ *
+ * @funcParams Function func
+ * @funcReturn void
+ * @example file.eachLine(function(line) { print(line) })
+ */
public static ExtensionFunction eachLine(final File file) {
return new ExtensionFunction() {
public Object execute(Context cx, Scriptable scope, Scriptable
thisObj, java.lang.Object[] args)
Modified:
struts/flow/trunk/src/java/org/apache/struts/flow/sugar/ListExtensions.java
URL:
http://svn.apache.org/viewcvs/struts/flow/trunk/src/java/org/apache/struts/flow/sugar/ListExtensions.java?view=diff&r1=155134&r2=155135
==============================================================================
--- struts/flow/trunk/src/java/org/apache/struts/flow/sugar/ListExtensions.java
(original)
+++ struts/flow/trunk/src/java/org/apache/struts/flow/sugar/ListExtensions.java
Wed Feb 23 18:05:12 2005
@@ -22,24 +22,18 @@
/**
* Adds various function extensions to java.util.List implementations.
+ * @targetClass java.util.List
*/
public class ListExtensions {
- public static ExtensionFunction each(final List list) {
- return new ExtensionFunction() {
- public Object execute(Context cx, Scriptable scope, Scriptable
thisObj, java.lang.Object[] args) {
- Function func = (Function)args[0];
- Object[] param = new Object[1];
-
- for (Iterator i = list.iterator(); i.hasNext(); ) {
- param[0] = i.next();
- func.call(cx, scope, thisObj, param);
- }
- return null;
- }
- };
- }
-
+
+ /**
+ * Returns an immutable version of this list.
+ *
+ * @funcParams
+ * @funcReturn java.util.List
+ * @example frozenList = list.asImmutable()
+ */
public static ExtensionFunction asImmutable(final List list) {
return new ExtensionFunction() {
public Object execute(Context cx, Scriptable scope, Scriptable
thisObj, java.lang.Object[] args) {
@@ -48,6 +42,13 @@
};
}
+ /**
+ * Returns a synchronized version of this list.
+ *
+ * @funcParams
+ * @funcReturn java.util.List
+ * @example multiThreadList = list.asSynchronized()
+ */
public static ExtensionFunction asSynchronized(final List list) {
return new ExtensionFunction() {
public Object execute(Context cx, Scriptable scope, Scriptable
thisObj, java.lang.Object[] args) {
@@ -56,6 +57,14 @@
};
}
+ /**
+ * Pops the last item off the list. The last item will be returned and
removed
+ * from the list.
+ *
+ * @funcParams
+ * @funcReturn Object
+ * @example lastItem = list.pop()
+ */
public static ExtensionFunction pop(final List list) {
return new ExtensionFunction() {
public Object execute(Context cx, Scriptable scope, Scriptable
thisObj, java.lang.Object[] args) {
@@ -69,6 +78,13 @@
};
}
+ /**
+ * Sorts the list according to the natural order.
+ *
+ * @funcParams
+ * @funcReturn java.util.List
+ * @example sortedList = list.sort()
+ */
public static ExtensionFunction sort(final List list) {
return new ExtensionFunction() {
public Object execute(Context cx, Scriptable scope, Scriptable
thisObj, java.lang.Object[] args) {
@@ -78,6 +94,15 @@
};
}
+ /**
+ * Sorts the list using the passed function to determine order. The
function will receive
+ * two parameters, and should return > 0 if the first is greater, <
0 if the first
+ * is less, and 0 if equal.
+ *
+ * @funcParams Function func
+ * @funcReturn java.util.List
+ * @example sortedList = list.sort(function(val1, val2) { return
val1.compareTo(val2) })
+ */
public static ExtensionFunction sortEach(final List list) {
return new ExtensionFunction() {
public Object execute(final Context cx, final Scriptable scope,
final Scriptable thisObj, java.lang.Object[] args) {
@@ -102,9 +127,5 @@
return list;
}
};
- }
-
- public static int length(List list, Scriptable scope) {
- return list.size();
}
}
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
