This CL contains the the changes needed to build...

documentation/jsdoc-toolkit-templates/publish.js

 /*
  * Copyright 2009, Google Inc.
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are
  * met:
  *
  *     * Redistributions of source code must retain the above copyright
  * notice, this list of conditions and the following disclaimer.
@@ skipping 31 matching lines @@
   'Number': true,
   'object': true,
   'Object': true,
   '*': true,
   '...': true,
   'string': true,
   'String': true,
   'void': true,
   'undefined': true};
 var g_unknownTypes = { };
+var g_numErrors = 0;
 
 /**
  * Called automatically by JsDoc Toolkit.
  * @param {SymbolSet} symbolSet Set of all symbols in all files.
  */
 function publish(symbolSet) {
   publish.conf = {  // trailing slash expected for dirs
     ext: '.ezt',
     outDir: JSDOC.opt.d || SYS.pwd + '../out/jsdoc/',
     templatesDir: JSDOC.opt.t || SYS.pwd + '../templates/jsdoc/',
     symbolsDir: '',
-    prefix: 'js_1_0_'};
+    prefix: JSDOC.opt.D.prefix || 'js_1_0_'};
   publish.conf.srcDir = publish.conf.outDir + 'src/'
   publish.conf.htmlDir = publish.conf.outDir + 'original_html/'
 
   // is source output is suppressed, just display the links to the source file
   if (JSDOC.opt.s && defined(Link) && Link.prototype._makeSrcLink) {
     Link.prototype._makeSrcLink = function(srcFilePath) {
       return '<' + srcFilePath + '>';
     }
   }
 
@@ skipping 13 matching lines @@
   try {
     var templatesDir = publish.conf.templatesDir;
     var classTemplate = new JSDOC.JsPlate(templatesDir + 'class.tmpl');
     var membersTemplate = new JSDOC.JsPlate(templatesDir + 'members.tmpl');
     var classTreeTemplate = new JSDOC.JsPlate(templatesDir + 'classtree.tmpl');
     var fileListTemplate = new JSDOC.JsPlate(templatesDir + 'filelist.tmpl');
     var annotatedTemplate = new JSDOC.JsPlate(templatesDir + 'annotated.tmpl');
     var namespacesTemplate = new JSDOC.JsPlate(templatesDir +
                                                'namespaces.tmpl');
   } catch(e) {
-    print('Couldn\'t create the required templates: ' + e);
-    quit();
+    generateError('Couldn\'t create the required templates: ' + e);
+    System.exit(1);
   }
 
   // some ustility filters
   function hasNoParent($) {return ($.memberOf == '')}
   function isaFile($) {return ($.is('FILE'))}
   function isaClass($) {return ($.is('CONSTRUCTOR') || $.isNamespace)}
 
   // get an array version of the symbolset, useful for filtering
   var symbols = symbolSet.toArray();
 
@@ skipping 56 matching lines @@
   var fileList = fileListTemplate.process(symbols);
   IO.saveFile(publish.conf.outDir, 'filelist.html', fileList);
 
   var annotated = annotatedTemplate.process(classes);
   IO.saveFile(publish.conf.outDir, 'annotated' + publish.conf.ext, annotated);
   IO.saveFile(publish.conf.htmlDir, 'annotated.html', annotated);
 
   var namespaces = namespacesTemplate.process(classes);
   IO.saveFile(publish.conf.outDir, 'namespaces' + publish.conf.ext, namespaces);
   IO.saveFile(publish.conf.htmlDir, 'namespaces.html', namespaces);
+
+  if (g_numErrors > 0) {
+    print('Num Errors: ' + g_numErrors);
+    System.exit(1);
+  }
 }
 
 
 /**
  *  Gets just the first sentence (up to a full stop).
  *  Should not break on dotted variable names.
  *  @param {string} desc Description to extract summary from.
  *  @return {string} summary.
  */
 function summarize(desc) {
@@ skipping 245 matching lines @@
 function camelCaseToUnderscore(str) {
   function toUnderscore(match) {
     return '_' + match.toLowerCase();
   }
   return str[0].toLowerCase() +
       str.substring(1).replace(/[A-Z]/g, toUnderscore);
 }
 
 /**
  * Prints a warning about an unknown type only once.
+ * @param {string} place Use to print error message if type not found.
  * @param {string} type Type specification.
  */
-function reportUnknownType(type) {
+function reportUnknownType(place, type) {
   if (!g_unknownTypes[type]) {
     g_unknownTypes[type] = true;
-    print ('WARNING: reference to unknown type: "' + type + '"');
+    generatePlaceError (place, 'reference to unknown type: "' + type + '"');
   }
 }
 
 /**
  * Gets index of closing character.
  * @param {string} str string to search.
  * @param {number} startIndex index to start searching at. Must be an opening
  *      character.
  * @return {number} Index of closing character or (-1) if not found.
  */
@@ skipping 30 matching lines @@
           return startIndex;
         }
       }
     }
     ++startIndex;
   }
   return -1;
 }
 
 /**
+ * Make's a name by concatenating strings.
+ * @param {...[string]} strings to concatenate.
+ * @return {string} Concatenated string.
+ */
+function makeName() {
+  var str = '';
+  for (var ii = 0; ii < arguments.length; ++ii) {
+    if (str) {
+      str += '.';
+    }
+    str += arguments[ii];
+  }
+  return str;
+}
+
+/**
+ * Generates an error msg.
+ * @param {string} msg.
+ */
+function generateError(msg) {
+  ++g_numErrors;
+  print('ERROR: ' + msg);
+}
+
+/**
+ * Generates an error msg.
+ * @param {string} place Use to print error message.
+ * @param {string} msg.
+ */
+function generatePlaceError(place, msg) {
+  generateError(place + ': ' + msg);
+}
+
+/**
  * Converts a reference to a single JSDOC type specification to an html link.
+ * @param {string} place Use to print error message if type not found.
  * @param {string} str to linkify.
  * @return {string} linkified string.
  */
-function linkifySingleType(type) {
+function linkifySingleType(place, type) {
   var not = '';
   var equals = '';
   // Remove ! if it exists.
   if (type[0] == '!') {
     not = '!'
     type = type.substring(1);
   }
   if (endsWith(type, '=')) {
     equals = '=';
     type = type.substring(0, type.length - 1);
   }
 
   var link = type;
 
   // Check for array wrapper.
   if (startsWith(type, 'Array.<')) {
     var closingAngle = getIndexOfClosingCharacter(type, 6);
     if (closingAngle < 0) {
-      print ('WARNING: Unmatched "<" in Array type : ' + type);
+      generatePlaceError(place, 'Unmatched "<" in Array type : ' + type);
     } else {
       link = 'Array.&lt;' +
-        linkifySingleType(type.substring(7, closingAngle)) + '>';
+        linkifySingleType(place, type.substring(7, closingAngle)) + '>';
     }
   } else if (startsWith(type, 'function(')) {
     var closingParen = getIndexOfClosingCharacter(type, 8);
     if (closingParen < 0) {
-      print ('WARNING: Unmatched "(" in function type : ' + type);
+      generatePlaceError(place, 'Unmatched "(" in function type : ' + type);
     } else {
       var end = type.substring(closingParen + 1);
       if (!startsWith(end, ': ')) {
-        print ('WARNING: Malformed return specification on function. Must be' +
-               ' "function(args): type" including the space after the colon.');
+        generatePlaceError(place,
+            'Malformed return specification on function. Must be' +
+            ' "function(args): type" including the space after the colon.');
       } else {
-        var args = type.substring(9, closingParen).split(/ *, */);
         var output = '';
-        for (var ii = 0; ii < args.length; ++ii) {
-          if (ii > 0) {
-            output += ', ';
+        var argsStr = type.substring(9, closingParen);
+        if (argsStr) {
+          var args = argsStr.split(/ *, */);
+          for (var ii = 0; ii < args.length; ++ii) {
+            if (ii > 0) {
+              output += ', ';
+            }
+            output += linkifyTypeSpec(place, args[ii]);
           }
-          output += linkifyTypeSpec(args[ii]);
         }
-        link = 'function(' + output + '): ' + linkifyTypeSpec(end.substring(2));
+        link = 'function(' + output + '): ' +
+               linkifyTypeSpec(place, end.substring(2));
       }
     }
   } else if (type.indexOf(':') >= 0) { // check for records.
-    var elements = type.split(/\s*,\s*/);
-    var output = '{';
-    for (var ii = 0; ii < elements.length; ++ii) {
-      if (ii > 0) {
-        output += ', ';
+    if (type.indexOf('::') >= 0) { // check for CPP scope
+      generatePlaceError(place,
+                         'CPP "::" scope operator found for type "' + type +
+                         '" must be Javascript "." scope operator.');
+    } else {
+      var elements = type.split(/\s*,\s*/);
+      var output = '{';
+      for (var ii = 0; ii < elements.length; ++ii) {
+        if (ii > 0) {
+          output += ', ';
+        }
+        var element = elements[ii];
+        var colon = element.indexOf(': ');
+        if (colon < 0) {
+          generatePlaceError(place,
+                             'Malformed record specification. Format must be ' +
+                             '{id1: type1, id2: type2, ...}.');
+          output += element;
+        } else {
+          var name = element.substring(0, colon);
+          var subType = element.substring(colon + 2);
+          output += name + ':&nbsp;' + linkifyTypeSpec(place, subType)
+        }
       }
-      var element = elements[ii];
-      var colon = element.indexOf(': ');
-      if (colon < 0) {
-        print ("WARNING: Malformed record specification. Format must be " +
-               "{id1: type1, id2: type2, ...}.");
-        output += element;
-      } else {
-        var name = element.substring(0, colon);
-        var subType = element.substring(colon + 2);
-        output += name + ':&nbsp;' + linkifyTypeSpec(subType)
-      }
+      link = output + '}';
     }
-    link = output + '}';
   } else {
     var symbol = getSymbol(type);
     if (symbol) {
       link = '<a class="el" href="' + getLinkToSymbol(symbol) + '">' +
           type + '</a>';
-    } else if (startsWith(type, 'o3d.')) {
-      // TODO: remove this hack, make nixysa generate JSDOC js
-      //     files instead of C++ headers and pass those into
-      //     jsdoctoolkit.
-      reportUnknownType(type);
-      link = '<a class="el" href="../classo3d_1_1_' +
-          camelCaseToUnderscore(type.substring(4)) + '.html">' +
-          type + '</a>';
     } else {
       // See if the symbol is a property or field.
       var period = type.lastIndexOf('.');
       if (period >= 0 && type != '...') {
         var subType = type.substring(0, period);
         symbol = getSymbol(subType);
         if (symbol) {
           var field = type.substring(period + 1);
           link = '<a class="el" href="' + getLinkToSymbol(symbol) + '#' +
               field + '">' +  type + '</a>';
         } else {
-          if (subType[0] == '?') {
-            subType = subType.substring(1);
-          }
-          if (!g_validJSDOCTypes[subType]) {
-            reportUnknownType(type);
+          if (startsWith(type, 'o3d.')) {
+            // TODO(gman): remove this hack, make nixysa generate JSDOC js
+            //     files instead of C++ headers and pass those into
+            //     jsdoctoolkit.
+            reportUnknownType(place, type);
+            link = '<a class="el" href="../classo3d_1_1_' +
+                camelCaseToUnderscore(type.substring(4)) + '.html">' +
+                type + '</a>';
+          } else {
+            if (subType[0] == '?') {
+              subType = subType.substring(1);
+            }
+            if (!g_validJSDOCTypes[subType]) {
+              reportUnknownType(place, type);
+            }
           }
         }
       }
     }
   }
 
   return not + link + equals;
 }
 
 /**
@@ skipping 16 matching lines @@
   } else {
     return str.replace(/\|/g, ', ');
   }
 }
 
 /**
  * Converts a JSDOC type specification into html links. For example
  * '(!o3djs.math.Vector3|!O3D.math.Vector4)' would change to
  * '(!<a href="??">o3djs.math.Vector3</a>
  * |!<a href="??">o3djs.math.Vector4</a>)'.
+ * @param {string} place Use to print error message if type not found.
  * @param {string} str to linkify.
  * @return {string} linkified string.
  */
-function linkifyTypeSpec(str) {
+function linkifyTypeSpec(place, str) {
   var output = '';
   if (str) {
     var fixed = fixSpecCommas(str);
     // TODO: needs to split outside of parens and angle brackets.
     if (startsWith(fixed, '(') && endsWith(fixed, ')')) {
       var types = fixed.substring(1, fixed.length - 1).split('|');
       output += '(';
       for (var tt = 0; tt < types.length; ++tt) {
         if (tt > 0) {
           output += '|';
         }
-        output += linkifySingleType(types[tt]);
+        output += linkifySingleType(place, types[tt]);
       }
       output += ')';
     } else {
-      output += linkifySingleType(fixed);
+      output += linkifySingleType(place, fixed);
     }
+  } else {
+    generatePlaceError(place, 'missing type specification (' + str + ')');
   }
   return output;
 }
 
 /**
+ * Same as linkifyTypeSpec but allows str to be undefined or ''.
+ * @param {string} place Use to print error message if type not found.
+ * @param {string} str to linkify.
+ * @return {string} linkified string.
+ */
+function linkifyTypeSpecForReturn(place, str) {
+  if (str) {
+    return linkifyTypeSpec(place, str);
+  }
+  return '';
+}
+
+/**
  * Gets a symbol for a type.
  * This is here mostly for debugging so you can insert a print before or after
  * each call to g_symbolSet.getSymbol.
  * @param {string} type fully qualified type.
  * @return {Symbol} The symbol object for the type or null if not found.
  */
 function getSymbol(type) {
   return g_symbolSet.getSymbol(type);
 }
 
 /**
  * Gets the source path for a symbol starting from 'o3djs/'
  * @param {!Symbol} symbol The symbol to get the source name for.
  * @return {string} The name of the source file.
  */
 function getSourcePath(symbol) {
   var path = symbol.srcFile.replace(/\\/g, '/');
   var index = path.indexOf('/o3djs/');
   return path.substring(index + 1);
 }