|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--xbn.XBNObject | +--xbn.programs.XBNStatic | +--jsutil.GenerateJSDoc
Generates JavaDoc-like documentation for a set of JavaScript code.
Source code: GenerateJSDoc.java
///
') list of relative paths to every JavaScript file you want to document. Must contain the ending '.js', and be properly formatted (as defined below). The order of this list is the order in which the table-of-contents is printed. If you need to provide a heck-of-a-lot of files (which DOS doesn't like), then set this alternatively to [[file=full_path_of_file]]
. That file must contain each item on a separate line, with no blank lines. Line separator must equal System.getProperty("line.separator")
Every gap must be surrounded by ~G~
and ~EG~
. For example:
~G~all_toc_items~EG~
To display the tilde character ('~
') literally, use '\~
'.
Must contain at least this one gap. May or may not contain others.
Gap | Filled with |
[The value of command-line parameter six] |
The accumulation of every 'JavaScript file table of contents item' Template result. |
js_file_toc_item.tmpl
)Must contain exactly this set of unique gap names:
Gap | Filled with |
rurl_overall_to_js_dir |
The url to link from the table of contents page to the directory in which all JavaScript documentation files exist, including the final slash ('/'). This is the value of command-line parameter five, exactly as you provided. |
js_file_no_post |
The name the JavaScript file, minus the '.js'. |
js_summary |
The first full line of the JS FILE OVERVIEW DOCUMENTATION block for this JavaScript file. |
js_file.html
)Must contain exactly this set of unique gap names:
Gap | Filled with |
rurl_js_dir_to_overall |
The relative url from the JS-directory to the overall template. This is the value of parameter eight, exactly as provided. |
js_file_no_post |
The name of the JavaScript file, excluding the '.js' postfix. |
js_summary |
The first full line of the JS FILE OVERVIEW DOCUMENTATION block for this JavaScript file. |
function_list |
Every function table of contents item, concatenated together. |
js_description |
The entire contents of the JS FILE OVERVIEW DOCUMENTATION block. |
all_function_sections |
Every function section, concatenated together. |
function_toc_item.tmpl
)Must contain exactly this set of unique gap names:
Gap | Filled with |
func_name |
The name of this function, minus parameters and parenthesis. |
func_summary |
The first line of the PUBLIC FUNCTION block. |
function_section.tmpl
)Must contain exactly this set of unique gap names:
Gap | Filled with |
js_file_no_post |
The name of the JavaScript file, excluding the '.js' postfix. |
func_name |
The name of this function, minus parameters and parenthesis. |
func_description |
The entire contents of the PUBLIC FUNCTION block. |
Assume these template files...
C:\test_gjsdoc\template\
index.html
I choose to store this in the same directory, even though this is not requiredjs_file_toc_item.tmpl
js_file.html
function_toc_item.tmpl
function_section.tmpl
...and these JavaScript files:
C:\test_gjsdoc\js\
util_string.js
utility.js
more_js\
Command line
First copy the overall template from source to destination:
copy C:\test_gjsdoc\template\index.html C:\test_gjsdoc\output\index.html
And then:
java jsutil.GenerateJSDoc C:\test_gjsdoc\template\ C:\test_gjsdoc\js\ util_string.js///utility.js///more_js\util_array.js C:\test_gjsdoc\output\ C:\test_gjsdoc\output\index.html main_all_js_file_toc_items > C:\test_gjsdoc\output\gjsdoc.log
Here is the final output and the log.
GenerateJSDoc.java
, a multi-line comment is one that starts with a line, after trim()
-ing, equal to '/**
' and ending with a line, after trim()
-ing, equal to '**/
'. Any '/**
' or '**/
' that shares the line with other non-whitespace characters is ignored./*
' and ends with '*/
'. Either may be surrounded by non-whitespace. In GenerateJSDoc.java
, the following multi-line comments are both legal and safely ignored:/* Single-lined multi-line comment */
/* Single-lined multi-line comment **/
/** Single-lined multi-line comment **/
/** A single-lined mlc **/ /** Another s-l mlc **/
/*
Semi-multi-lined multi-line
comment **/
/*
Semi-multi-lined multi-line comment
***/
/** Semi-multi-lined multi-line comment
*/
GenerateJSDoc.java
, because exactly one of '/**
' or '**/
' has whitespace around it, but not the other (or the other does not have two asterisks):/* Single-lined multi-line comment
**/
/*
Single-lined multi-line comment
**/
/**
Single-lined multi-line comment **/
/**
Semi-multi-lined multi-line comment
*/
/**
Semi-multi-lined multi-line comment
***/
/** A single-lined mlc **/ /**
Another s-l mlc
**/
trim()
-ing, equal to 'JS FILE OVERVIEW DOCUMENTATION
'. This is considered the overview marker. There is only one overview block per JavaScript file. Any blocks or multi-line comments existing before the overview block is ignored (although checked for syntax). The second and subsequent overview blocks are ignored.trim()
-ing, equal to 'PUBLIC FUNCTION'
. This is considered the function marker. Any function block existing before the overview block is ignored (although they are still checked for syntax). Function block documentation (in the table of contents, and in the body) are output in the order they actually exist in the js file./**
' and the block marker are allowed.trim()
-ing with '<P>'
and '</P>'
, and must contain at least one character between the 'P' tags. There must be a summary line in each block. In other words, aside from the marker, at least one non-whitespace line (starting with '<P>' and ending with '</P>') must exist in each block.function myFunction{
'trim()
-ing, with . The last function signature line is the first line after (or the same line as the one in which) the function signature begins, that ends with (after trim()
-ing) an end brace: '{
'. A multi-line function signature is one in which 'function
' exists on a line before its end-brace. No matter what 'function
', the function name, and the open parenthesis must exist on the first line of the function signature.State descriptions and key:
bInMLC
(imlc
): Are we currently in a multi-line comment? A multi-line comment, in GenerateJSDoc.java
, is considered starting with a line, after trim()
-ming, entirely equal to /**
and ending with a line entirely equal to **/
bNeedOverviewBlock
(nov
): Has the overview block been fully retrieved? Function blocks existing before the overview block are ignored. Is initialized to true, and remains that way until the entire overview block is retrieved.bInOverviewBlock
(iov
): Are we in the midst of the overview block? This will only equal true when bInMLC
equals true, and the overview marker was found.bInFunctionBlock
(ifn
): Are we in the midst of a function block? This will only equal true when bInMLC
is true, bNeedOverviewBlock
is false, and the function marker was found.bNeedSummaryLine
(nsm
): Do we need the summary line for the overview/function block? Will only be true when both bInMLC
and bInOverviewBlock
-or-bInFunctionBlock
are true, but no non-whitespace lines have yet been found after the function/block marker.bNeedFuncSignature
(nfg
): Do we need to retrieve the function signature? Is set to true when bInFunctionBlock
is set to true, and will remain true until the function signature is completely retrieved after the end of the function block
1
|
'x' means true, no value means 'false'
|
Field Summary | |
static String |
sJS_FILE_SEP
The JavaScript file separator. |
static String |
sMLC_SLSH_STR_STR
The multi-line comment start delimiter. |
static String |
sMLC_STR_STR_SLSH
The multi-line comment end delimiter. |
static String |
sMRKR_FUNCTION
The Function block marker |
static String |
sMRKR_OVERVIEW
The JavaScript file overview block marker |
Fields inherited from class xbn.XBNObject |
bFALSE_IN_PRODUCTION, bTRUE_IN_PRODUCTION, sCNSTR, sES, sLINE_SEP |
Constructor Summary | |
GenerateJSDoc()
|
Method Summary | |
static void |
main(String[] as_cmdLineParams)
|
Methods inherited from class xbn.programs.XBNStatic |
throwAXS |
Methods inherited from class xbn.XBNObject |
getXMsgPrefix, sop, sopl, sopl, throwAX, throwAXIfBadStr, throwAXIfNull, throwAXSpoof |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static String sJS_FILE_SEP
The JavaScript file separator.
Equal to '///'
public static String sMRKR_OVERVIEW
The JavaScript file overview block marker
Equal to 'JS FILE OVERVIEW DOCUMENTATION'
public static String sMRKR_FUNCTION
The Function block marker
Equal to 'PUBLIC FUNCTION'
public static String sMLC_SLSH_STR_STR
The multi-line comment start delimiter.
Equal to '/' + '**'**
public static String sMLC_STR_STR_SLSH
The multi-line comment end delimiter.
Equal to '**' + '/'
Constructor Detail |
public GenerateJSDoc()
Method Detail |
public static void main(String[] as_cmdLineParams)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 2003-2005, Jeff Epstein, All Rights Reserved. See top of source code files for copyright notice.
http://sourceforge.net/projects/jsutiljava