General Interface is an open source project hosted by the Dojo Foundation

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&reg;
    # The title of the compiled API documentation, XML-escaped
    gi.apidocs.title.esc = My Library&amp;reg;
    # The copyright of the compiled API documentation, XML-escaped
    gi.apidocs.copyright = Copyright &amp;copy; 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.

Contents

Searching General Interface Docs

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.