JsUnit
JsUnit |
|
|
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.
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:
///
//!
/**< */
///<
/*!< */
//!< */
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
|