f, writing jsdoc to
* file out.
* @param f input file
* @param fname name of the input file (without the path)
* @param inputdir directory of the input file
* @param out output file
*/
function processFile(f, fname, inputdir, out) {
var s;
var firstLine = true;
indexFileArray[fname] = "";
// write the header of the output file
out.writeLine('Index Files '; outstr += 'Index Functions
" +
"function " + name + "(" + args + ")" +
"" +
processComment(comment,0,name) +
"
";
}
/**
* Process a method being bound to a prototype.
* @param proto the name of the prototype
* @param name the name of the function
* @param args the args of the function as a single string
* @param comment the text of the comment
* @return a string for the HTML text of the documentation
*/
function processPrototypeMethod(proto, name, args, comment) {
if (debug)
print("Processing " + proto + ".prototype." + name + " " + args + " " + comment);
return "
" +
proto + ".prototype." + name + " = function(" + args + ")" +
"" +
processComment(comment,0,name) +
"
";
}
/**
* Process comment.
* @param comment the text of the comment
* @param firstLine shows if comment is at the beginning of the file
* @param fname name of the file (without path)
* @return a string for the HTML text of the documentation
*/
function processComment(comment,firstLine,fname) {
var tags = {};
// Use the "lambda" form of regular expression replace,
// where the replacement object is a function rather
// than a string. The function is called with the
// matched text and any parenthetical matches as
// arguments, and the result of the function used as the
// replacement text.
// Here we use the function to build up the "tags" object,
// which has a property for each "@" tag that is the name
// of the tag, and whose value is an array of the
// text following that tag.
comment = comment.replace(/@(\w+)\s+([^@]*)/g,
function (s, name, text) {
var a = tags[name] || [];
a.push(text);
tags[name] = a;
return "";
});
// if we have a comment at the beginning of a file
// store the comment for the index file
if (firstLine) {
indexFileArray[fname] = comment;
}
var out = comment + '
'; if (tags["param"]) { // Create a table of parameters and their descriptions. var array = tags["param"]; var params = ""; for (var i=0; i < array.length; i++) { var m = array[i].match(/(\w+)\s+(.*)/); params += '
| Parameter | '; out += 'Description |
'; } if (tags["return"]) { out += "
"; } if (tags["author"]) { // List the authors together, separated by commas. out += '
'; } if (tags["version"]) { // Show the version. out += '
';
}
if (tags["see"]) {
// List the see modules together, separated by
.
out += '
'; } if (tags["lastmodified"]) { // Shows a last modified description with client-side js. out += '
';
}
// additional tags can be added here (i.e., "if (tags["see"])...")
return out;
}
/**
* Create an html output file
* @param outputdir directory to put the file
* @param htmlfile name of the file
*/
function CreateOutputFile(outputdir,htmlfile)
{
if (outputdir==null)
{
var outname = htmlfile;
}
else
{
var separator = Packages.java.io.File.separator;
var outname = outputdir + separator + htmlfile.substring(htmlfile.lastIndexOf(separator),htmlfile.length);
}
print("output file: " + outname);
return new File(outname);
}
/**
* Process a javascript file. Puts the generated HTML file in the outdir
* @param filename name of the javascript file
* @inputdir input directory of the file (default null)
*/
function processJSFile(filename,inputdir)
{
if (debug) print("filename = " + filename + " inputdir = " + inputdir);
if (!filename.match(/\.js$/)) {
print("Expected filename to end in '.js'; had instead " +
filename + ". I don't treat the file.");
} else {
if (inputdir==null)
{
var inname = filename;
}
else
{
var separator = Packages.java.io.File.separator;
var inname = inputdir + separator + filename;
}
print("Processing file " + inname);
var f = new File(inname);
// create the output file
var htmlfile = filename.replace(/\.js$/, ".html");
var out = CreateOutputFile(outputdir,htmlfile);
processFile(f, filename, inputdir, out);
out.close();
}
}
/**
* Generate index files containing links to the processed javascript files
* and the generated functions
*/
function GenerateIndex(dirname)
{
// construct the files index file
var out = CreateOutputFile(outputdir,indexFile);
// write the beginning of the file
out.writeLine('File Index - directory: ' + dirname + '
\n');
out.writeLine('');
out.writeLine('
');
out.close();
// construct the functions index file
var out = CreateOutputFile(outputdir,indexFunction);
// write the beginning of the file
out.writeLine('');
out.writeLine(' ');
var separator = Packages.java.io.File.separator;
// sort the index file array
var SortedFileArray = [];
for (var fname in indexFileArray)
SortedFileArray.push(fname);
SortedFileArray.sort();
for (var i=0; i < SortedFileArray.length; i++) {
var fname = SortedFileArray[i];
var htmlfile = fname.replace(/\.js$/, ".html");
out.writeLine('File ');
out.writeLine('Description ' + fname + ' ');
if (indexFileArray[fname])
out.writeLine(indexFileArray[fname]);
else
out.writeLine('No comments');
out.writeLine(' Function Index - directory: ' + dirname + '
\n');
out.writeLine('');
out.writeLine('
');
out.close();
}
/**
* prints the options for JSDoc
*/
function PrintOptions()
{
print("You can use the following options:\n");
print("-d: specify an output directory for the generated html files\n");
print("-i: processes all files in an input directory (you can specify several directories)\n");
quit();
}
// Main Script
// first read the arguments
if (! arguments)
PrintOptions();
for (var i=0; i < arguments.length; i++) {
if (debug) print("argument: + \'" + arguments[i] + "\'");
if (arguments[i].match(/^\-/)) {
if (String(arguments[i])=="-d"){
// output directory for the generated html files
outputdir = String(arguments[i+1]);
if (debug) print("outputdir: + \'" + outputdir + "\'");
i++;
}
else if (String(arguments[i])=="-i"){
// process all files in an input directory
DirList.push(String(arguments[i+1]));
if (debug) print("inputdir: + \'" + arguments[i+1] + "\'");
i++;
}
else {
print("Unknown option: " + arguments[i] + "\n");
PrintOptions();
}
}
else
{
// we have a single file
if (debug) print("file: + \'" + arguments[i] + "\'");
FileList.push(String(arguments[i]));
}
}
// first handle the single files
for (var i in FileList)
processJSFile(FileList[i],null);
// then handle the input directories
for (var j in DirList) {
var inputdir = String(DirList[j]);
print("Process input directory: " + inputdir);
// clean up index arrays
var indexFileArray = [];
var indexFunctionArray = [];
// for the directory name get rid of ../../ or ..\..\
inputDirName = inputdir.replace(/\.\.\/|\.\.\\/g,"");
indexFile = indexFileName + "_" + inputDirName + ".html";
indexFunction = indexFunctionName + "_" + inputDirName + ".html";
print("indexFile = " + indexFile);
print("indexFunction = " + indexFunction);
// read the files in the directory
var DirFile = new java.io.File(inputdir);
var lst = DirFile.list();
var separator = Packages.java.io.File.separator;
for (var i=0; i < lst.length; i++)
{
processJSFile(String(lst[i]),inputdir);
}
// generate the index files for the input directory
GenerateIndex(inputDirName);
}
');
out.writeLine(' ');
// sort the function array
var SortedFunctionArray = [];
for (var functionname in indexFunctionArray)
SortedFunctionArray.push(functionname);
SortedFunctionArray.sort();
for (var j=0; j < SortedFunctionArray.length; j++) {
var funcname = SortedFunctionArray[j];
with (indexFunctionArray[funcname]) {
var outstr = 'Function ');
out.writeLine('Files ' + funcname + ' ';
var filelst = filename.split("|");
for (var i in filelst) {
var htmlfile = filelst[i].replace(/\.js$/, ".html");
outstr += '' + filelst[i] + ' ';
}
outstr += '