Author: mrdon
Date: Sun Apr 17 22:36:29 2005
New Revision: 161732
URL: http://svn.apache.org/viewcvs?view=rev&rev=161732
Log:
Adding more docs and xdoc generation system
Added:
struts/flow/trunk/src/doc/extensions2xdoc.xsl (with props)
struts/flow/trunk/src/doc/jsdoc2xdoc.xsl (with props)
Modified:
struts/flow/trunk/build.xml
struts/flow/trunk/src/doc/extensions.xdt
struts/flow/trunk/src/doc/jsdoc.js
struts/flow/trunk/src/java/org/apache/struts/flow/Struts.java
struts/flow/trunk/src/java/system.js
Modified: struts/flow/trunk/build.xml
URL:
http://svn.apache.org/viewcvs/struts/flow/trunk/build.xml?view=diff&r1=161731&r2=161732
==============================================================================
--- struts/flow/trunk/build.xml (original)
+++ struts/flow/trunk/build.xml Sun Apr 17 22:36:29 2005
@@ -138,31 +138,53 @@
<delete dir="${doc.dir}" />
</target>
+
<target name="doc.extensions" depends="prepare">
- <delete dir="${build.doc}"/>
+ <delete dir="${build.doc}/extensions"/>
<taskdef name="doclet"
classname="xdoclet.DocletTask"
classpathref="base.classpath"/>
- <doclet destdir="${build.doc}" verbose="true">
+ <doclet destdir="${build.doc}/extensions" verbose="true">
<fileset dir="${src.java}" includes="**/*Extensions.java"/>
<template templateFile="${src.doc}/extensions.xdt"
destinationFile="extensions.xml"/>
</doclet>
+
+ <xslt basedir="${build.doc}/extensions" includes="extensions.xml"
destdir="${build.doc}"
+ extension=".xml" style="${src.doc}/extensions2xdoc.xsl" />
</target>
- <target name="doc.jsdoc" depends="prepare">
+ <!--
+ <target name="doc.extensions" depends="prepare">
+ <delete dir="${build.doc}/jsobjects"/>
<taskdef name="doclet"
classname="xdoclet.DocletTask"
classpathref="base.classpath"/>
+ <doclet destdir="${build.doc}/jsobjects" verbose="true">
+ <fileset dir="${src.java}"
includes="org/apache/struts/flow/Struts.java"/>
+ <template templateFile="${src.doc}/jsobjects.xdt"
destinationFile="struts.xml"/>
+ </doclet>
+
+ <xslt basedir="${build.doc}/jsobjects" includes="*.xml"
destdir="${build.doc}"
+ extension=".xml" style="${src.doc}/jsobjects2xdoc.xsl" />
+ </target>
+ -->
+ <target name="doc.jsdoc" depends="compile">
+ <delete dir="${build.doc}/jsdoc"/>
+ <mkdir dir="${build.doc}/jsdoc" />
+
<java classname="org.apache.struts.flow.sugar.SugarWrapFactory">
<arg value="${src.doc}/jsdoc.js" />
<arg value="-d" />
- <arg value="${build.doc}"/>
+ <arg value="${build.doc}/jsdoc"/>
<arg value="-i" />
<arg value="${src.java}"/>
<classpath refid="base.classpath" />
</java>
+
+ <xslt basedir="${build.doc}/jsdoc" includes="*.xml"
destdir="${build.doc}"
+ extension=".xml" style="${src.doc}/jsdoc2xdoc.xsl" />
</target>
<!--
Modified: struts/flow/trunk/src/doc/extensions.xdt
URL:
http://svn.apache.org/viewcvs/struts/flow/trunk/src/doc/extensions.xdt?view=diff&r1=161731&r2=161732
==============================================================================
--- struts/flow/trunk/src/doc/extensions.xdt (original)
+++ struts/flow/trunk/src/doc/extensions.xdt Sun Apr 17 22:36:29 2005
@@ -26,7 +26,7 @@
</XDtMethod:ifHasMethodTag>
</XDtMethod:ifIsPublic>
</XDtMethod:forAllMethods>
+ </class>
</XDtClass:ifHasClassTag>
- </class>
</XDtClass:forAllClasses>
</extensions>
Added: struts/flow/trunk/src/doc/extensions2xdoc.xsl
URL:
http://svn.apache.org/viewcvs/struts/flow/trunk/src/doc/extensions2xdoc.xsl?view=auto&rev=161732
==============================================================================
--- struts/flow/trunk/src/doc/extensions2xdoc.xsl (added)
+++ struts/flow/trunk/src/doc/extensions2xdoc.xsl Sun Apr 17 22:36:29 2005
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet version="1.0"
+xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
+>
+ <xsl:output method="xml" />
+
+ <xsl:template match="/">
+ <xsl:apply-templates />
+ </xsl:template>
+
+ <xsl:template match="extensions">
+<document url="extensions.html">
+ <xsl:comment>
+ WARNING: This file is automatically generated from an xdoclet extension
that
+ turns javadoc tags in the extensions Java source code into an xml file,
+ which is then processed by an xsl file to create this document. Do not
+ modify this file, but rather either modify the comments or xsl file.
+ </xsl:comment>
+ <properties>
+ <title>Java API Extensions</title>
+ </properties>
+ <body>
+ <section name="Java API Extensions" href="summary">
+
+ <p>
+ Struts Flow adds properties and methods to Java API classes to make
using the Java API easier in the flow scripts. Each documented extension
listed here includes a description and example of its use.
+ </p>
+ <xsl:for-each select="class">
+ <strong><xsl:value-of select="name" /></strong>
+ <blockquote>
+ <table>
+ <xsl:for-each select="method">
+ <tr>
+ <td><xsl:value-of select="type" /></td>
+ <td>
+ <a href="#{../name}_{name}"><xsl:value-of select="name"
/></a>(<xsl:value-of select="params" />) -
+ <xsl:value-of select="firstSentence" /></td>
+ </tr>
+ </xsl:for-each>
+ </table>
+ </blockquote>
+ </xsl:for-each>
+ </section>
+ <xsl:apply-templates select="class" />
+ </body>
+</document>
+ </xsl:template>
+
+
+ <xsl:template match="class">
+ <section name="{name}" href="cls_{name}">
+ <xsl:apply-templates />
+ </section>
+ </xsl:template>
+
+ <xsl:template match="method">
+ <section name="{name}" href="{../name}_{name}">
+<pre>
+ <xsl:value-of select="concat(type,' ',name,'(',params,')')" />
+</pre>
+ <blockquote>
+ <p><xsl:value-of select="comment" disable-output-escaping="yes"/>
+ </p>
+ <dl>
+ <dt><strong>Example:</strong></dt>
+ <dd><code><xsl:value-of select="example" /></code></dd>
+ </dl>
+ </blockquote>
+ </section>
+ </xsl:template>
+
+ <xsl:template match="text()" />
+
+</xsl:stylesheet>
Propchange: struts/flow/trunk/src/doc/extensions2xdoc.xsl
------------------------------------------------------------------------------
svn:executable = *
Modified: struts/flow/trunk/src/doc/jsdoc.js
URL:
http://svn.apache.org/viewcvs/struts/flow/trunk/src/doc/jsdoc.js?view=diff&r1=161731&r2=161732
==============================================================================
--- struts/flow/trunk/src/doc/jsdoc.js (original)
+++ struts/flow/trunk/src/doc/jsdoc.js Sun Apr 17 22:36:29 2005
@@ -75,12 +75,12 @@
indexFileArray[fname] = "";
// write the header of the output file
- out.append('<HTML><HEADER><TITLE>' + fname + '</TITLE><BODY>');
- if (inputdir != null) {
- outstr = '<a name=\"_top_\"></a><pre><a href=\"' + indexFile +
'\">Index Files</a> ';
- outstr += '<a href=\"' + indexFunction + '\">Index
Functions</a></pre><hr>';
- out.append(outstr);
- }
+ out.append('<jsdoc><fileName>' + fname + '</fileName>');
+ //if (inputdir != null) {
+ // outstr = '<a name=\"_top_\"></a><pre><a href=\"' + indexFile +
'\">Index Files</a> ';
+ // outstr += '<a href=\"' + indexFunction + '\">Index
Functions</a></pre><hr>';
+ // out.append(outstr);
+ //}
// process the input file
var lines = f.getLines();
@@ -108,9 +108,7 @@
if (firstLine) {
// We have a comment for the whole file.
- out.append('<H1>File ' + fname + '</H1>');
out.append(processComment(comment,firstLine,fname));
- out.append('<HR>');
firstLine = false;
comment = "";
continue;
@@ -124,6 +122,7 @@
{
// Found a function start
var htmlText = processFunction(m[1], m[5], comment); //
sjm changed from 2nd to 5th arg
+ out.append(htmlText);
// Save the text in a global variable, so we
// can write out a table of contents first.
@@ -152,6 +151,8 @@
// Found a method being bound to a prototype.
var htmlText = processPrototypeMethod(m[1], m[2], m[3],
comment);
+ out.append(htmlText);
+
// Save the text in a global variable, so we
// can write out a table of contents first.
functionDocArray[functionDocArray.length] =
{name:m[1]+".prototype."+m[2], text:htmlText};
@@ -177,6 +178,7 @@
firstLine = false;
}
+ /*
// Write table of contents.
for (var i=0; i < functionDocArray.length; i++) {
with (functionDocArray[i]) {
@@ -185,6 +187,7 @@
}
}
out.append('<HR>');
+
// Now write the saved function documentation.
for (i=0; i < functionDocArray.length; i++) {
@@ -193,7 +196,8 @@
out.append(text);
}
}
- out.append('</BODY></HTML>');
+ */
+ out.append('</jsdoc>');
// Now clean up the doc array
functionDocArray = [];
@@ -210,12 +214,10 @@
function processFunction(name, args, comment) {
if (debug)
print("Processing " + name + " " + args + " " + comment);
- return "<H2>Function " + name + "</H2>" +
- "<PRE>" +
- "function " + name + "(" + args + ")" +
- "</PRE>" +
+ return "<function><name>" + name + "</name>" +
+ "<args>" + args + "</args>" +
processComment(comment,0,name) +
- "<P><BR><BR>";
+ "</function>";
}
/**
@@ -229,12 +231,10 @@
function processPrototypeMethod(proto, name, args, comment) {
if (debug)
print("Processing " + proto + ".prototype." + name + " " + args + " " +
comment);
- return "<H2> Method " + proto + ".prototype." + name + "</H2>" +
- "<PRE>" +
- proto + ".prototype." + name + " = function(" + args + ")" +
- "</PRE>" +
+ return "<prototypeFunction><type>" + proto + "</type><name>" + name +
"</name>" +
+ "<args>" + args + "</args>" +
processComment(comment,0,name) +
- "<P><BR><BR>";
+ "</protytpeFunction>";
}
@@ -271,60 +271,29 @@
indexFileArray[fname] = comment;
}
- var out = comment + '<P>';
+ var out = "<comment><![CDATA[" + comment + "]]></comment>";
if (tags["param"]) {
// Create a table of parameters and their descriptions.
var array = tags["param"];
- var params = "";
for (var i=0; i < array.length; i++) {
var m = array[i].match(/(\w+)\s+(.*)/);
- params += '<TR><TD><I>'+m[1]+'</I></TD>' +
- '<TD>'+m[2]+'</TD></TR>';
- }
- out += '<TABLE WIDTH="90%" BORDER=1>';
- out += '<TR BGCOLOR=0xdddddddd>';
- out += '<TD><B>Parameter</B></TD>';
- out += '<TD><B>Description</B></TD></TR>';
- out += params;
- out += '</TABLE><P>';
- }
- if (tags["return"]) {
- out += "<DT><B>Returns:</B><DD>";
- out += tags["return"][0] + "</DL><P>";
- }
- if (tags["author"]) {
- // List the authors together, separated by commas.
- out += '<DT><B>Author:</B><DD>';
- var array = tags["author"];
- for (var i=0; i < array.length; i++) {
- out += array[i];
- if (i+1 < array.length)
- out += ", ";
- }
- out += '</DL><P>';
- }
- if (tags["version"]) {
- // Show the version.
- out += '<DT><B>Version:</B><DD>';
- var array = tags["version"];
- for (var i=0; i < array.length; i++) {
- out += array[i];
- if (i+1 < array.length)
- out += "<BR><DD>";
- }
- out += '</DL><P>';
- }
- if (tags["see"]) {
- // List the see modules together, separated by <BR>.
- out += '<DT><B>Dependencies:</B><DD>';
- var array = tags["see"];
- for (var i=0; i < array.length; i++) {
- out += array[i];
- if (i+1 < array.length)
- out += "<BR><DD>";
+ out += '<param><name>' + m[1] + '</name>';
+ out += '<description>' + m[2] + '</description>';
+ out += "</param>";
}
- out += '</DL><P>';
+
}
+ for (tag in tags) {
+ if (tag != "param") {
+ var array = tags[tag];
+ if (array != null && array.length > 0) {
+ for (var i=0; i < array.length; i++) {
+ out += '<' + tag + '>' + array[i] + '</' + tag + '>';
+ }
+ }
+ }
+ }
+ /*
if (tags["lastmodified"]) {
// Shows a last modified description with client-side js.
out += '<DT><B>Last modified:</B><DD>';
@@ -333,6 +302,7 @@
out += '// ---></script>\n';
out += '</DL><P>';
}
+ */
// additional tags can be added here (i.e., "if (tags["see"])...")
return out;
@@ -388,7 +358,7 @@
var f = new java.io.File(inname);
// create the output file
- var htmlfile = filename.replace(/\.js$/, ".html");
+ var htmlfile = filename.replace(/\.js$/, ".xml");
var out = CreateOutputFile(outputdir,htmlfile);
@@ -406,13 +376,7 @@
var out = CreateOutputFile(outputdir,indexFile);
// write the beginning of the file
- out.append('<HTML><HEADER><TITLE>File Index - directory: ' + dirname +
'</TITLE><BODY>');
- out.append('<H1>File Index - directory: ' + dirname + '</H1>\n');
- out.append('<TABLE WIDTH="90%" BORDER=1>');
- out.append('<TR BGCOLOR=0xdddddddd>');
- out.append('<TD><B>File</B></TD>');
- out.append('<TD><B>Description</B></TD></TR>');
-
+ out.append('<jsdoc type="index"><directory>' + dirname + '</directory>');
var separator = Packages.java.io.File.separator;
// sort the index file array
@@ -423,15 +387,14 @@
for (var i=0; i < SortedFileArray.length; i++) {
var fname = SortedFileArray[i];
- var htmlfile = fname.replace(/\.js$/, ".html");
- out.append('<TR><TD><A HREF=\"' + htmlfile + '\">' + fname +
'</A></TD></TD><TD>');
+ //var htmlfile = fname.replace(/\.js$/, ".html");
+ out.append('<file><name>' + fname + '</name>');
+
if (indexFileArray[fname])
- out.append(indexFileArray[fname]);
- else
- out.append('No comments');
- out.append('</TD></TR>\n');
+ out.append('<description>' + indexFileArray[fname] +
'</description>');
+ out.append('</file>\n');
}
- out.append('</TABLE></BODY></HTML>');
+ out.append('</jsdoc>');
// construct the functions index file
var out = CreateOutputFile(outputdir,indexFunction);
@@ -556,7 +519,7 @@
}
// generate the index files for the input directory
- GenerateIndex(inputDirName);
+ //GenerateIndex(inputDirName);
}
Added: struts/flow/trunk/src/doc/jsdoc2xdoc.xsl
URL:
http://svn.apache.org/viewcvs/struts/flow/trunk/src/doc/jsdoc2xdoc.xsl?view=auto&rev=161732
==============================================================================
--- struts/flow/trunk/src/doc/jsdoc2xdoc.xsl (added)
+++ struts/flow/trunk/src/doc/jsdoc2xdoc.xsl Sun Apr 17 22:36:29 2005
@@ -0,0 +1,98 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet version="1.0"
+xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
+>
+ <xsl:output method="xml" />
+
+ <xsl:template match="/">
+ <xsl:apply-templates />
+ </xsl:template>
+
+ <xsl:template match="jsdoc">
+ <xsl:variable name="name" select="substring(fileName, 0,
string-length(fileName) - 3)" />
+<document url="{$name}.html">
+ <xsl:comment>
+ WARNING: This file is automatically generated from a jsdoc processor that
+ turns javadoc-type comments of Javascript files into an xml file, which is
+ then processed by an xsl file to create this document. Do not modify this
+ file, but rather either modify the comments or xsl file.
+ </xsl:comment>
+ <properties>
+ <title>File <xsl:value-of select="fileName" /></title>
+ </properties>
+ <body>
+ <xsl:variable name="title">
+ <xsl:if test="title"><xsl:value-of select="title" /></xsl:if>
+ <xsl:if test="not(title)"><xsl:value-of select="concat('File
',fileName)" /></xsl:if>
+ </xsl:variable>
+ <section name="{title}" href="summary">
+ <p>
+ <xsl:value-of select="comment" disable-output-escaping="yes"/>
+ </p>
+ <dl>
+ <xsl:apply-templates select="author" />
+ <xsl:apply-templates select="version" />
+ <xsl:apply-templates select="see" />
+ </dl>
+ <hr />
+ <strong>Functions</strong>
+ <blockquote>
+ <xsl:for-each select="function">
+ <a href="#{concat('fn_',name)}"><xsl:value-of select="name"
/></a>(<xsl:value-of select="args" />)<br />
+ </xsl:for-each>
+ </blockquote>
+ </section>
+ <xsl:apply-templates select="function" />
+ </body>
+</document>
+ </xsl:template>
+
+ <xsl:template match="author">
+ <dt><strong>Author: </strong></dt><dd><xsl:value-of select="." /></dd>
+ </xsl:template>
+
+ <xsl:template match="see">
+ <dt><strong>See Also: </strong></dt><dd><xsl:value-of select="." /></dd>
+ </xsl:template>
+
+ <xsl:template match="version">
+ <dt><strong>Version: </strong></dt><dd><xsl:value-of select="." /></dd>
+ </xsl:template>
+
+ <xsl:template match="return">
+ <dt><strong>Returns: </strong></dt><dd><xsl:value-of select="." /></dd>
+ </xsl:template>
+
+ <xsl:template match="function">
+ <section name="{name}" href="fn_{name}">
+<pre>
+ <xsl:value-of select="concat(name,'(',args,')')" />
+</pre>
+ <p><xsl:value-of select="comment" disable-output-escaping="yes"/>
+ </p>
+ <xsl:if test="param">
+ <table>
+ <tr>
+ <th>Parameter</th>
+ <th>Description</th>
+ </tr>
+ <xsl:for-each select="param">
+ <tr>
+ <td><xsl:value-of select="name" /></td>
+ <td><xsl:value-of select="description" /></td>
+ </tr>
+ </xsl:for-each>
+ </table>
+ </xsl:if>
+ <dl>
+ <xsl:apply-templates select="return" />
+ <xsl:apply-templates select="version" />
+ <xsl:apply-templates select="see" />
+ <xsl:apply-templates select="throws" />
+ </dl>
+ </section>
+ </xsl:template>
+
+ <xsl:template match="text()" />
+
+</xsl:stylesheet>
Propchange: struts/flow/trunk/src/doc/jsdoc2xdoc.xsl
------------------------------------------------------------------------------
svn:executable = *
Modified: struts/flow/trunk/src/java/org/apache/struts/flow/Struts.java
URL:
http://svn.apache.org/viewcvs/struts/flow/trunk/src/java/org/apache/struts/flow/Struts.java?view=diff&r1=161731&r2=161732
==============================================================================
--- struts/flow/trunk/src/java/org/apache/struts/flow/Struts.java (original)
+++ struts/flow/trunk/src/java/org/apache/struts/flow/Struts.java Sun Apr 17
22:36:29 2005
@@ -28,6 +28,8 @@
/**
* Access to Struts and Servlet resources
+ *
+ * @jsname struts
*/
public class Struts {
Modified: struts/flow/trunk/src/java/system.js
URL:
http://svn.apache.org/viewcvs/struts/flow/trunk/src/java/system.js?view=diff&r1=161731&r2=161732
==============================================================================
--- struts/flow/trunk/src/java/system.js (original)
+++ struts/flow/trunk/src/java/system.js Sun Apr 17 22:36:29 2005
@@ -1,5 +1,18 @@
/**
- * System methods to simplify interactions with the flow engine.
+ * <p>
+ * These methods are available to every flow script automatically to simplify
+ * interactions with the flow engine. They can be overridden as necessary for
+ * advanced customizations like intercepting every function call to perform
some
+ * common logic like security checks.
+ * </p>
+ *
+ * <p>The only method that should be called from an application's flow scripts
+ * is <a href="#fn_forwardAndWait">forwardAndWait()</a> as the others are
mainly
+ * just used by the framework.
+ * They are exposed to allow the user to easily customize functionality.
+ * </p>
+ *
+ * @title Core Flow Methods
*/
var suicide;
@@ -37,7 +50,8 @@
/**
* Forwards to a page and creates a continuation. Contains special support
* for client FlowCall's (calling flow functions through asynchrous javascript
- * calls from the client.
+ * calls from the client). The forward name will be used to find the
+ * appropriate Struts ActionForward to return from the Action.
*
* @param name The Struts forward name to call
* @param atts Map of business objects to place in the request scope
@@ -87,9 +101,10 @@
}
/**
- * Do the actual work to forward to a page and create a continuation. The
+ * Does the actual work to forward to a page and create a continuation. The
* forward name, continuation id, and business object map are passed through
- * <code>flow</code> context values.
+ * <code>flow</code> context values. This method shouldn't be called from
+ * flow scripts but the method forwardAndWait() should be called instead.
*
* @param name The Struts forward to call
* @param atts The business object map to make available to the page
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
