JsUnit
Project Developer Home doxygen

Internals

Internal Developer's Guide

Document Conventions

The documentation of JavaScript code follows the JavaDoc conventions. The generation is done using a Perl script generating Pseudo C++ code with the comments that is processed afterwards with DoxyGen. A lot of the features of DoxyGen are supported including the QT style of the comments. See following chapter how to generate the documentation.

Documentation blocks within the code are embedded with:

/**
 *
 */

First element of such a block has to be a tag identifying the documented element or is directly a brief description of the next code element. Within the code following elements are supported:

Other elements like @type or @enum are ignored. The element type @ctor is introduced by the Perl script to allow a separate description of the class' constructor that is simply the initializer function of the class. The class itself is identified by assigning elements to its prototype. For an interface only functions should be added to the prototype.

Unlike C++ JavaScript has no idea about variable or function types. Since this information is nevertheless valuable for the documentation the script supports some tags that allow the type specification to be generated in the pseudo code:

@tparam TYPE PARAM COMMENT
This command sets the type of a parameter. It is replaced in the documentation comment with the @param PARAM COMMENT command (without the TYPE).

@tparam TYPE COMMENT
This command sets the return type of a function. It is replaced in the documentation comment with the @return COMMENT command (without the TYPE). This comand is a short cut of the normal @return command and the @type command supported by this program.

@type TYPE
This command sets the type of a variable or the return type of a function.

Keep in mind that C++ pseudo code is produced. Unlike in C++ it is quite not clear which elements will belong in the end to a class. Therefore the script cannot support the grouping commands of DoxyGen.

Script Manual

NAME
    js2doxy - utility to convert JavaScript into something Doxygen can
    understand

SYNOPSIS
     js2doxy.pl < file.js > file.cpp
     js2doxy.pl [Options] file.js

     Options:

     -?     Print usage
     -d, --debug    Debug mode
     -h, --help Show manual
     -v, --version  Print version

OPTIONS
    -?      Prints the usage of the script.

    --debug Prints internal states to the error stream. States are triggered
            by single bits:

             Bit 0: Dump (1)
             Bit 1: Database (2)
             Bit 2: Detector (4)
             Bit 3: Parser (8)
             Bit 4: Scanner (16)

    --help  Shows the manual pages of the script using perldoc.

    --version
            Print the version of the utility and exits.

DESCRIPTION
    This program will read from standard input or from the given input file
    and convert the input into pseudo C++ that can be understood by help
    generator Doxygen. The program parses the JavaScript and tries to attach
    the correct documentation comments. Any unattached comment is placed
    into file scope.

HELP COMMANDS
    The program will accept some additional help commands to produce better
    C++:

    \ctor   This command starts the description of the constructor. It can
            be placed within the documentation comment for a class. It may
            be used also as first command in such a comment.

    \tparam TYPE PARAM COMMENT
            This command sets the type of a parameter. It is replaced in the
            documentation comment with the \param PARAM COMMENT command
            (without the TYPE). The program will use the type information in
            the generated C++ code. It may not be the first command in a
            documentation comment.

    \treturn TYPE COMMENT
            This command sets the return type of a function. It is replaced
            in the documentation comment with the \return COMMENT command
            (without the TYPE). The program will use the type information in
            the generated C++ code. It may not be the first command in a
            documentation comment. This comand is a short cut of the normal
            \return command and the \type command supported by this program.

    \type TYPE
            This command sets the type of a variable or the return type of a
            function. It may not be the first command in a documentation
            comment.

LIMITATIONS
    The program uses internally a has map for the database. Therefore the
    sequence of the identified elements is by chance and the grouping
    commands of Doxygen are not supported.

    The program does currently not support single line documentation blocks
    or documentation blocks that *follow* the declaration:

     ///
     //!
     /**< */
     ///<
     /*!< */
     //!< */


Rebuilding Documentation

Like everyone I am not very keen on writing documentation. The best way I can live with it is the way javadoc supports this. Luckily there are some other tools out there that can be used for other languages, but most of these tools are only available for object-oriented languages. While JavaScript allows to write object-oriented code, most people are not aware of this. Therefore I use a perl script to transform JavaScript code that follow the coding conventions above in some kind of pseudo C++ that can be used to fool Doxygen, my favorite non-Java source code documentation tool.

Use the script jsdoc to rebuild the documentation. It is located in the util directory. It depends on a Unix environment including Perl. In Windows I personally use Cygwin that comes nowadays with quite complete Unix packages. Additionally you have to install Doxygen and Graphviz a cross-platform drawing toolkit from AT&T. My script expects both tools either in the PATH or at /opt/doxygen and /opt/graphviz. In Windows I have mounted my Windows program files folder to /opt using Cygwin functionality. (Nowadays Cygwin offers also doxygen as prebuild package, but it is quite outdated and works only at binary mounts.)

My script will call the Perl script js2doxy.pl to generate pseudo C++. Then it calls Doxygen to generate the first version of the HTML documentation. At last text processing is done with sed to generate the JsUnit color style in the headers.


JsUnit © 1999, 2000, 2001, 2002, 2003, 2006, 2007 by Jörg Schaible
Generated on Wed Apr 15 2015 02:33:06 for JsUnit by doxygen 1.8.5