jsutil
Class GenerateJSDoc

java.lang.Object
  |
  +--xbn.XBNObject
        |
        +--xbn.programs.XBNStatic
              |
              +--jsutil.GenerateJSDoc

public class GenerateJSDoc
extends XBNStatic

Generates JavaDoc-like documentation for a set of JavaScript code.

Source code:  GenerateJSDoc.java

Command line parameters

  1. The full path to the template directory. All templates but the 'overall' one must exist in this directory.
  2. The base path on which the relative paths in parameter three are based.
  3. A tokenized (by '///') 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")
  4. The full path to the directory in which the documentation page for every item in parameter three is written to. Must be an existing and writeable directory. Existing files are overwritten.
  5. The full path to the final location of the overall template, containing the table-of-contents gap. Must exist, and contain at least the gap named in parameter six.
  6. The name of the table of contents gap that must exist in the overall template. It need not be the only gap, but this one at least must exist.
  7. The relative url from the overall template to the directory defined in parmeter four, including the final url slash ('/'). If not provided, then empty string ('') is assumed. Both this and eight must be either provided or not provided.
  8. The relative url from the directory defined in parmeter four, to the overall template, including the final url slash ('/'). If not provided, then empty string ('') is assumed. Both this and seven must be either provided or not provided.

Template-s

Every gap must be surrounded by ~G~ and ~EG~. For example:
   ~G~all_toc_items~EG~

To display the tilde character ('~') literally, use '\~'.

(example)   Overall

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.

(example)   JavaScript file table of contents item (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.

(example)   JavaScript file overall (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.

(example)   Function toc entry (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.

(example)   Function body (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.

Example

Assume these template files...

...and these JavaScript files:

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.

Technical details

State descriptions and key:

1
2   /**
3      PUBLIC FUNCTION
4
5      <P>A function summary line</P>
6      <P>Function documentation</P>
7    **/
8   function myFunction(with, parameters)  {
9   ...
10   }
11
12
13   /**
14      Some block we should ignore
15    **/
16
17
18   /**
19      JS FILE OVERVIEW DOCUMENTATION
20
21      <P>My OHD summary line</P>
22      <P>Overview doucemnation</P>
23    **/
24
25
26   /**
27      Another block we should ignore
28    **/
29
30
31
32   /**
33      PUBLIC FUNCTION
34
35      <P>A function summary line</P>
36      <P>Function documentation</P>
37    **/
38   function myFunction(with, a, whole,
39                       lot, of, parameters)&nbsp;
40   {
41   ...
42   }
43
44
45   /**
46      JS FILE OVERVIEW DOCUMENTATION
47
48      <P>My OHD summary line</P>
49      <P>Overview doucemnation</P>
50    **/
51
52
53   /**
54      PUBLIC FUNCTION
55
56      <P>A function only a summary line</P>
57    **/
58   function myFunction2(with, parameters)  {
59   ...
60   }
61
62
63   /**
64      Another block we should ignore
65    **/
66
67   

'x' means true, no value means 'false'

After line
analyzed
nov imlc iov ifn nsm nfg
1 x          
2-6 x x        
7-12 x          
13-14 x x        
15-17 x          
18 x x        
19-20 x x x   x  
21-22 x x x      
23-25            
26-27   x        
28-31            
32   x        
33-34   x   x x x
35-36   x   x   x
37           x
38-40           x
41-44            
45   x        
46-49   x        
50-52            
53   x        
54-55   x   x x x
56   x   x   x
57           x
58-62            
63-64   x        
65-67            


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

sJS_FILE_SEP

public static String sJS_FILE_SEP

The JavaScript file separator.

Equal to '///'


sMRKR_OVERVIEW

public static String sMRKR_OVERVIEW

The JavaScript file overview block marker

Equal to 'JS FILE OVERVIEW DOCUMENTATION'


sMRKR_FUNCTION

public static String sMRKR_FUNCTION

The Function block marker

Equal to 'PUBLIC FUNCTION'


sMLC_SLSH_STR_STR

public static String sMLC_SLSH_STR_STR

The multi-line comment start delimiter.

Equal to '/' + '**'**


sMLC_STR_STR_SLSH

public static String sMLC_STR_STR_SLSH

The multi-line comment end delimiter.

Equal to '**' + '/'

Constructor Detail

GenerateJSDoc

public GenerateJSDoc()
Method Detail

main

public static void main(String[] as_cmdLineParams)



Copyright 2003-2005, Jeff Epstein, All Rights Reserved. See top of source code files for copyright notice.

 

http://sourceforge.net/projects/jsutiljava

 

SourceForge.net Logo