Running JSXDOC

JSXDOC is distributed with the source distribution of General Interface as a Java class with an Ant task interface. The easiest way to run JSXDOC is via the Ant interface.

To get started:

1. Make sure that Java 1.5+ and Ant 1.7+ are installed. Downloads are available at http://java.sun.com and http://ant.apache.org.
2. Download the GI source distribution from at http://www.generalinterface.org. Unzip it to GI_SRC.
3. Run the command ant package in the directory GI_SRC/build/tools. This creates a jsx-tools.jar file in same directory. The JAR file contains the JSXDOC program and Ant task.
4. Copy jsx-tools.jar and the following files into a new directory, JSX_RUN.

   GI_SRC/build/tools/lib/javacc/bin/lib/javacc.jar
   GI_SRC/build/tools/lib/jaxen/jaxen-1.1.jar
   GI_SRC/build/tools/lib/dojo/jsl.jar
   GI_SRC/build/tools/lib/xml/xalan-serializer-2.7.jar
   GI_SRC/build/tools/lib/saxon/saxon8.jar
   GI_SRC/build/tools/lib/saxon/saxon8-dom.jar
   GI_SRC/build/apidoc/

5. Now create an Ant build.xml file in JSX_RUN.
6. Copy the following example as a starting point.

   <project name="General Interface Documentation Compiler" default="jsxdoc" basedir=".">
   
     <target name="init">
       <property file="build.properties"/>
     </target>
   
     <!-- Initializes substitution tokens used in text file copying. -->
     <target name="init-filters" depends="init">
       <filterset id="filters">
         <filtersfile file="build.properties"/>
       </filterset>
     </target>
   
     <target name="init-tools" depends="init">
       <path id="cp.tools">
         <path path="jsx-tools.jar"/>
         <path path="javacc.jar"/>
         <path path="jaxen-1.1.jar"/>
         <path path="jsl.jar"/>
         <path path="xalan-serializer-2.7.jar"/>
         <path path="saxon8.jar"/>
         <path path="saxon8-dom.jar"/>
       </path>
   
       <taskdef resource="com/tibco/gi/ant/antlib.xml" classpathref="cp.tools"/>
     </target>
   
     <target name="jsxdoc" depends="init, jsxdoc-xml, jsxdoc-html"
         description="Compiles the API documentation contained in the JavaScript files placed in the src/ directory.">
     </target>
   
     <target name="jsxdoc-xml" depends="init-tools">
       <echo message="Compiling the XML documentation for the JavaScript files in ${js.dir}."/>
       <echo message="The XML documentation files will be saved in ${doc.dir.xml}."/>
       <gi-doc destdir="${doc.dir.xml}" access="${jsxdoc.access}">
         <fileset dir="${xsl.dir}" includes="javascript.js"/>
         <fileset dir="${js.dir}" includes="**/*.js"/>
       </gi-doc>
     </target>
   
     <target name="jsxdoc-html" depends="init-filters, init-tools">
       <mkdir dir="${tmp.dir}"/>
   
       <!-- Copy XSLT to temporary directory with filtering. -->
       <copy todir="${tmp.dir}" verbose="false" encoding="${jsxdoc.encoding}">
         <filterset refid="filters"/>
         <fileset dir="${xsl.dir}">
           <include name="*.xsl"/>
           <include name="*.html"/>
           <include name="*.css"/>
         </fileset>
       </copy>
   
       <echo message="Compiling the HTML documentation for the XML files in ${doc.dir.xml}."/>
       <echo message="The HTML documentation files will be saved in ${doc.dir.html}."/>
       <gi-htmldoc
           srcdir="${doc.dir.xml}"
           destdir="${doc.dir.html}"
           docdir="${tmp.dir}"/>
   
       <delete dir="${tmp.dir}"/>
     </target>
   
   </project>

7. In the same directory, create the Ant build.properties file from the following template. The build.properties file allows you to configure the Ant build process without modifying the build.xml file.

   # The title of the compiled API documentation
   gi.apidocs.title = My Library®
   # The title of the compiled API documentation, XML-escaped
   gi.apidocs.title.esc = My Library®
   # The copyright of the compiled API documentation, XML-escaped
   gi.apidocs.copyright = Copyright © My Company
   
   # The minimum access level of documented members: public, protected, private
   jsxdoc.access = protected
   jsxdoc.encoding = UTF-8
   
   xsl.dir = apidoc
   js.dir = src
   tmp.dir = tmp
   doc.dir.xml = doc/xml
   doc.dir.html = doc/html

8. Place all JavaScript source files in the directory JSX_RUN/src.
9. Run the ant command from JSX_RUN. The build process is configured to export XML documentation to JSX_RUN/doc/xml/ and HTML documentation to JSX_RUN/doc/html/.
10. Open JSXRUN/doc/html/index.html in a web browser to view the new documentation.