Added comments and some docs to ant build

diff --git a/build.xml b/build.xml
index 49596e9..3966492 100644 (file)
--- a/build.xml
+++ b/build.xml
@@ -1,173 +1,194 @@
-<project name="jQuery" default="all" basedir=".">\r
+<project name="jQuery" default="all" basedir=".">
+       
+       <!--
+       - Using this build file to create your own custom distribution -
+       
+       If you want to include jQuery on your site with a certain set of plugins,
+       follow these steps to create your custom build:
+       
+       1. Copy the plugins you need to the plugins folder (if you haven't already, checkout
+          the plugins folder from SVN.
+       2. Modify the PLUGINS property to include all plugins you want, see PLUGINS_ALL for syntax
+          eg. if you need form and tabs plugin, set the value for PLUGINS to this:
+          form/*.js, tabs/*.js
+       3. Execute the standard jquery and packed targets to build your distribution
+
+       TODO Using this build file to create docs for a single plugin
+       -->\r
 \r
        <!-- SETUP -->
 
-    <property name="SRC_DIR" value="src" />
-    <property name="BUILD_DIR" value="build" />
-    <property name="JAR" value="${BUILD_DIR}/js.jar" />\r
+       <property description="Source Folder" name="SRC_DIR" value="src" />
+       <property description="Files executefor parsing etc." name="BUILD_DIR" value="build" />
+       <property description="Rhino JS Engine" name="JAR" value="${BUILD_DIR}/js.jar" />\r
 \r
-       <property name="PLUGIN_DIR" location="../plugins" />\r
-       <property name="PLUGINS" value="none" />
-       <property name="PLUGINS_ALL" value="button/*.js,center/*.js,cookie/*.js,form/*.js,greybox/*.js,interface/*.js,pager/*.js,tablesorter/*.js,tabs/*.js" />\r
+       <property description="Dir to look for plugins" name="PLUGIN_DIR" location="../plugins" />\r
+       <property description="Add single plugins here" name="PLUGINS" value="none" />
+       <property description="Add all plugins here" name="PLUGINS_ALL" 
+               value="button/*.js,center/*.js,cookie/*.js,form/*.js,greybox/*.js,interface/*.js,pager/*.js,tablesorter/*.js,tabs/*.js" />\r
 
-    <property name="PREFIX" value="." />
-    <property name="DOCS_DIR" value="${PREFIX}/docs" />
-    <property name="TEST_DIR" value="${PREFIX}/test" />
-    <property name="DIST_DIR" value="${PREFIX}/dist" />
+       <property description="Target parent folder for built files" name="PREFIX" value="." />
+       <property description="Folder for docs target" name="DOCS_DIR" value="${PREFIX}/docs" />
+       <property description="Folder for test target" name="TEST_DIR" value="${PREFIX}/test" />
+       <property description="Folder for jquery, min, lite and packed target" name="DIST_DIR" value="${PREFIX}/dist" />
 
-    <property name="JQ" value="${DIST_DIR}/jquery.js" />
-    <property name="JQ_LITE" value="${DIST_DIR}/jquery.lite.js" />
-    <property name="JQ_MIN" value="${DIST_DIR}/jquery.min.js" />
-    <property name="JQ_PACK" value="${DIST_DIR}/jquery.pack.js" />\r
-\r
-       <property name="TABS" value="${PLUGIN_DIR}/tabs/tabs.js" />\r
-       <property name="TABS_PACK" value="${DIST_DIR}/jquery.tabs.pack.js" />\r
+       <!-- Files names for distribution -->
+       <property name="JQ" value="${DIST_DIR}/jquery.js" />
+       <property name="JQ_LITE" value="${DIST_DIR}/jquery.lite.js" />
+       <property name="JQ_MIN" value="${DIST_DIR}/jquery.min.js" />
+       <property name="JQ_PACK" value="${DIST_DIR}/jquery.pack.js" />\r
 \r
        <!-- MAIN -->\r
 \r
-    <target name="jquery">
-        <echo message="Building ${JQ}" />
-        <mkdir dir="${DIST_DIR}" />
-        <concat destfile="${JQ}">\r
-               <fileset dir="${SRC_DIR}" includes="intro.js" />
-            <fileset dir="${SRC_DIR}" includes="jquery/*.js" />
-            <fileset dir="${SRC_DIR}" includes="event/*.js" />
-            <fileset dir="${SRC_DIR}" includes="fx/*.js" />
-            <fileset dir="${SRC_DIR}" includes="ajax/*.js" />\r
-               <fileset dir="${PLUGIN_DIR}" includes="${PLUGINS}" />\r
-               <fileset dir="${SRC_DIR}" includes="outro.js" />
-        </concat>
-        <echo message="${JQ} built." />
-    </target>
-       
-       <target name="jquery_with_plugins" description="Build jquery with all plugins">
+       <target name="jquery" description="Main jquery build, set PLUGINS property to include plugins">
+               <echo message="Building ${JQ}" />
+               <mkdir dir="${DIST_DIR}" />
+               <concat destfile="${JQ}">\r
+                       <fileset dir="${SRC_DIR}" includes="intro.js" />
+                       <fileset dir="${SRC_DIR}" includes="jquery/*.js" />
+                       <fileset dir="${SRC_DIR}" includes="event/*.js" />
+                       <fileset dir="${SRC_DIR}" includes="fx/*.js" />
+                       <fileset dir="${SRC_DIR}" includes="ajax/*.js" />\r
+                       <fileset dir="${PLUGIN_DIR}" includes="${PLUGINS}" />\r
+                       <fileset dir="${SRC_DIR}" includes="outro.js" />
+               </concat>
+               <echo message="${JQ} built." />
+       </target>
+
+       <target name="jquery_with_plugins" description="Build jquery with all plugins, useful to full documentation">
                <antcall target="jquery">
                        <param name="PLUGINS" value="${PLUGINS_ALL}" />
                </antcall>\r
        </target>
 
-    <target name="lite" depends="jquery">
-        <echo message="Building ${JQ_LITE}" />
-        <java jar="${JAR}" fork="true">
-            <arg value="${BUILD_DIR}/build/lite.js" />
-            <arg value="${JQ}" />
-            <arg value="${JQ_LITE}" />
-        </java>
-        <echo message="${JQ_LITE} built." />
-    </target>
+       <target name="lite" depends="jquery" description="Remove all /** */ comments">
+               <echo message="Building ${JQ_LITE}" />
+               <java jar="${JAR}" fork="true">
+                       <arg value="${BUILD_DIR}/build/lite.js" />
+                       <arg value="${JQ}" />
+                       <arg value="${JQ_LITE}" />
+               </java>
+               <echo message="${JQ_LITE} built." />
+       </target>
 
-    <target name="min" depends="jquery">
-        <echo message="Building ${JQ_MIN}" />
-        <java jar="${JAR}" fork="true">
-            <arg value="${BUILD_DIR}/build/min.js" />
-            <arg value="${JQ}" />
-            <arg value="${JQ_MIN}" />
-        </java>
-        <echo message="${JQ_MIN} built." />
-    </target>
+       <target name="min" depends="jquery" description="Remove all comments and whitespace, no compression">
+               <echo message="Building ${JQ_MIN}" />
+               <java jar="${JAR}" fork="true">
+                       <arg value="${BUILD_DIR}/build/min.js" />
+                       <arg value="${JQ}" />
+                       <arg value="${JQ_MIN}" />
+               </java>
+               <echo message="${JQ_MIN} built." />
+       </target>
 
-    <target name="pack" depends="jquery">
-        <echo message="Building ${JQ_PACK}" />
-        <java jar="${JAR}" fork="true">
-            <arg value="${BUILD_DIR}/build/pack.js" />
-            <arg value="${JQ}" />
-            <arg value="${JQ_PACK}" />
-        </java>
-        <echo message="${JQ_PACK} built." />
-    </target>\r
-               \r
-    <target name="pack_with_plugins" depends="jquery_with_plugins">\r
-        <echo message="Building ${JQ_PACK}" />\r
-        <java jar="${JAR}" fork="true">\r
-            <arg value="${BUILD_DIR}/build/pack.js" />\r
-            <arg value="${JQ}" />\r
-            <arg value="${JQ_PACK}" />\r
-        </java>\r
-        <echo message="${JQ_PACK} built." />\r
-    </target>          
+       <target name="pack" depends="jquery" description="Remove all comments and whitespace and compress">
+               <echo message="Building ${JQ_PACK}" />
+               <java jar="${JAR}" fork="true">
+                       <arg value="${BUILD_DIR}/build/pack.js" />
+                       <arg value="${JQ}" />
+                       <arg value="${JQ_PACK}" />
+               </java>
+               <echo message="${JQ_PACK} built." />
+       </target>\r
+\r
+       <target name="pack_with_plugins" depends="jquery_with_plugins" description="Pack jquery with all plugins, not very useful">\r
+               <echo message="Building ${JQ_PACK}" />\r
+               <java jar="${JAR}" fork="true">\r
+                       <arg value="${BUILD_DIR}/build/pack.js" />\r
+                       <arg value="${JQ}" />\r
+                       <arg value="${JQ_PACK}" />\r
+               </java>\r
+               <echo message="${JQ_PACK} built." />\r
+       </target>
 
-    <target name="test" depends="jquery">
-        <echo message="Building Test Suite" />
-        <delete dir="${TEST_DIR}" />
-       <mkdir dir="${TEST_DIR}/data" />\r
-        <copy todir="${TEST_DIR}/data">\r
-               <fileset dir="${BUILD_DIR}/test/data/" />\r
-       </copy>\r
-        <java jar="${JAR}" fork="true">
-            <arg value="${BUILD_DIR}/test/test.js" />
-            <arg value="${JQ}" />
-            <arg value="${TEST_DIR}" />
-        </java>
-        <echo message="Test Suite built." />
-    </target>
+       <target name="test" depends="jquery" description="Reads tests from source and compiles into html file, testsuite must be run on a webserver">
+               <echo message="Building Test Suite" />
+               <delete dir="${TEST_DIR}" />
+               <mkdir dir="${TEST_DIR}/data" />\r
+               <copy todir="${TEST_DIR}/data">\r
+                       <fileset dir="${BUILD_DIR}/test/data/" />\r
+               </copy>\r
+               <java jar="${JAR}" fork="true">
+                       <arg value="${BUILD_DIR}/test/test.js" />
+                       <arg value="${JQ}" />
+                       <arg value="${TEST_DIR}" />
+               </java>
+               <echo message="Test Suite built." />
+       </target>
 
-    <target name="docs" depends="jquery">
-        <echo message="Building Documentation" />
-        <delete dir="${DOCS_DIR}" />
-        <mkdir dir="${DOCS_DIR}/data" />
-       <copy todir="${DOCS_DIR}" file="${BUILD_DIR}/docs/.htaccess" />
-        <mkdir dir="${DOCS_DIR}/js" />
-        <copy todir="${DOCS_DIR}/js" >
-            <fileset dir="${BUILD_DIR}/docs/js">
-                <include name="**/*.js"/>
-            </fileset>
-        </copy>
-               <copy todir="${DOCS_DIR}/style" >
-            <fileset dir="${BUILD_DIR}/docs/style">
-                <include name="**"/>
-            </fileset>
-        </copy>
-        <java jar="${JAR}" fork="true">
-            <arg value="${BUILD_DIR}/docs/docs.js" />
-            <arg value="${JQ}" />
-            <arg value="${DOCS_DIR}" />
-        </java>
-        <echo message="Documentation built." />
-    </target>\r
-               \r
-    <target name="docs_with_plugins" depends="jquery_with_plugins">\r
-        <echo message="Building Documentation" />\r
-        <delete dir="${DOCS_DIR}" />\r
-        <mkdir dir="${DOCS_DIR}/data" />\r
-       <copy todir="${DOCS_DIR}" file="${BUILD_DIR}/docs/.htaccess" />\r
-        <mkdir dir="${DOCS_DIR}/js" />\r
-        <copy todir="${DOCS_DIR}/js" >\r
-            <fileset dir="${BUILD_DIR}/docs/js">\r
-                <include name="**/*.js"/>\r
-            </fileset>\r
-        </copy>\r
-               <copy todir="${DOCS_DIR}/style" >\r
-            <fileset dir="${BUILD_DIR}/docs/style">\r
-                <include name="**"/>\r
-            </fileset>\r
-        </copy>\r
-        <java jar="${JAR}" fork="true">\r
-            <arg value="${BUILD_DIR}/docs/docs.js" />\r
-            <arg value="${JQ}" />\r
-            <arg value="${DOCS_DIR}" />\r
-        </java>\r
-        <echo message="Documentation built." />\r
-    </target>          
+       <target name="docs" depends="jquery" description="Reads inline docs from source and compiles into xml file">
+               <echo message="Building Documentation" />
+               <delete dir="${DOCS_DIR}" />
+               <mkdir dir="${DOCS_DIR}/data" />
+               <copy todir="${DOCS_DIR}" file="${BUILD_DIR}/docs/.htaccess" />
+               <mkdir dir="${DOCS_DIR}/js" />
+               <copy todir="${DOCS_DIR}/js">
+                       <fileset dir="${BUILD_DIR}/docs/js">
+                               <include name="**/*.js" />
+                       </fileset>
+               </copy>
+               <copy todir="${DOCS_DIR}/style">
+                       <fileset dir="${BUILD_DIR}/docs/style">
+                               <include name="**" />
+                       </fileset>
+               </copy>
+               <java jar="${JAR}" fork="true">
+                       <arg value="${BUILD_DIR}/docs/docs.js" />
+                       <arg value="${JQ}" />
+                       <arg value="${DOCS_DIR}" />
+               </java>
+               <echo message="Documentation built." />
+       </target>\r
 
-    <target name="clean">
-        <delete dir="${DOCS_DIR}" />
-        <delete dir="${TEST_DIR}" />
-        <delete dir="${DIST_DIR}" />
-    </target>
+       <!-- TODO refactor to remove duplication with above -->\r
+       <target name="docs_with_plugins" depends="jquery_with_plugins">\r
+               <echo message="Building Documentation" />\r
+               <delete dir="${DOCS_DIR}" />\r
+               <mkdir dir="${DOCS_DIR}/data" />\r
+               <copy todir="${DOCS_DIR}" file="${BUILD_DIR}/docs/.htaccess" />\r
+               <mkdir dir="${DOCS_DIR}/js" />\r
+               <copy todir="${DOCS_DIR}/js">\r
+                       <fileset dir="${BUILD_DIR}/docs/js">\r
+                               <include name="**/*.js" />\r
+                       </fileset>\r
+               </copy>\r
+               <copy todir="${DOCS_DIR}/style">\r
+                       <fileset dir="${BUILD_DIR}/docs/style">\r
+                               <include name="**" />\r
+                       </fileset>\r
+               </copy>\r
+               <java jar="${JAR}" fork="true">\r
+                       <arg value="${BUILD_DIR}/docs/docs.js" />\r
+                       <arg value="${JQ}" />\r
+                       <arg value="${DOCS_DIR}" />\r
+               </java>\r
+               <echo message="Documentation built." />\r
+       </target>
 
-    <target name="all" depends="clean,jquery,lite,min,pack,docs,test" >
-        <echo message="Build complete." />
-    </target>
+       <target name="clean">
+               <delete dir="${DOCS_DIR}" />
+               <delete dir="${TEST_DIR}" />
+               <delete dir="${DIST_DIR}" />
+       </target>
+
+       <target name="all" depends="clean,jquery,lite,min,pack,docs,test">
+               <echo message="Build complete." />
+       </target>
        
+       <!-- Extra stuff for Tabs plugin -->
+       
+       <property name="TABS" value="${PLUGIN_DIR}/tabs/tabs.js" />
+       <property name="TABS_PACK" value="${DIST_DIR}/jquery.tabs.pack.js" />
+
        <target name="pack_tabs">\r
-        <echo message="Building ${TABS_PACK}" />\r
+               <echo message="Building ${TABS_PACK}" />\r
                <mkdir dir="${DIST_DIR}" />\r
-        <java jar="${JAR}" fork="true">\r
-            <arg value="${BUILD_DIR}/build/pack.js" />\r
-            <arg value="${TABS}" />\r
-            <arg value="${TABS_PACK}" />\r
-        </java>\r
-        <echo message="${TABS_PACK} built." />\r
-    </target>\r
+               <java jar="${JAR}" fork="true">\r
+                       <arg value="${BUILD_DIR}/build/pack.js" />\r
+                       <arg value="${TABS}" />\r
+                       <arg value="${TABS_PACK}" />\r
+               </java>\r
+               <echo message="${TABS_PACK} built." />\r
+       </target>\r
 
 </project>