Added o3djs.util.getElementsByTagAndId and

o3djs.util.getO3DContainerElements which 
encasplulates the way we were finding elements
to make O3D tags in.

I also put an example of how to make your own
failure callback in the docs.

This also brought up a known issue in the doc
generator so that fix is included here.

Review URL: http://codereview.chromium.org/173178

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@23976 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 86 insertions, 22 deletions

diff --git a/o3d/documentation/jsdoc-toolkit-templates/publish.js b/o3d/documentation/jsdoc-toolkit-templates/publish.js
index cf1800c..9fe8736 100644
--- a/o3d/documentation/jsdoc-toolkit-templates/publish.js
+++ b/o3d/documentation/jsdoc-toolkit-templates/publish.js
@@ -64,6 +64,20 @@ var g_baseURL;
 var g_topURL;
 var g_templates = [];
 var g_o3dPropertyRE = /^(\w+)\s+(\w+)\s+/;
+var g_startContainerRE = /^(?:function\(|!function\(|[\(<{[])/;
+var g_containerRE = /function\(|!function\(|[\(<{[]/;
+var g_openCloseMap = {
+  'function(': ')',
+  '!function(': ')',
+  '(': ')',
+  '<': '>',
+  '[': ']',
+  '{': '}'};
+var g_closeMap = {
+  ')': true,
+  '>': true,
+  ']': true,
+  '}': true};
 
 /**
  * Called automatically by JsDoc Toolkit.
@@ -627,29 +641,18 @@ function reportUnknownType(place, type) {
  * @return {number} Index of closing character or (-1) if not found.
  */
 function getIndexOfClosingCharacter(str, startIndex) {
-  var openCloseMap = {
-    '(': ')',
-    '<': '>',
-    '[': ']',
-    '{': '}'};
-  var closeMap = {
-    ')': true,
-    '>': true,
-    ']': true,
-    '}': true,
-  };
   var stack = [];
-  if (!openCloseMap[str[startIndex]]) {
+  if (!g_openCloseMap[str[startIndex]]) {
     throw 'startIndex does not point to opening character.';
   }
   var endIndex = str.length;
   while (startIndex < endIndex) {
     var c = str[startIndex];
-    var closing = openCloseMap[c];
+    var closing = g_openCloseMap[c];
     if (closing) {
       stack.unshift(closing);
     } else {
-      closing = closeMap[c];
+      closing = g_closeMap[c];
       if (closing) {
         var expect = stack.shift()
         if (c != expect) {
@@ -762,6 +765,8 @@ function linkifySingleType(place, type) {
         var output = '';
         var argsStr = type.substring(9, closingParen);
         if (argsStr) {
+          // TODO(gman): This needs to split taking parens, brackets and angle
+          //    brackets into account.
           var args = argsStr.split(/ *, */);
           for (var ii = 0; ii < args.length; ++ii) {
             if (ii > 0) {
@@ -832,30 +837,85 @@ function linkifySingleType(place, type) {
 }
 
 /**
+ * Splits a string by containers. A string like "ab(cd,ef)gh" will
+ * be returned as ['ab', '(cd,ef)', 'gh']
+ * @param {string} str String to split.
+ * @return {!Array.<string>} The split string parts.
+ */
+function splitByContainers(str) {
+  var parts = [];
+  for (;;) {
+    var match = str.match(g_containerRE);
+    if (!match) {
+      if (str.length > 0) {
+        parts.push(str);
+      }
+      return parts;
+    }
+    var startIndex = str.indexOf(match);
+    if (startIndex != 0) {
+      parts.push(str.substring(0, startIndex));
+    }
+    var endIndex = getIndexOfClosingCharacter(
+        str, startIndex + match.toString().length - 1);
+    if (endIndex < 0) {
+      throw 'no closing character for "' + str[startIndex] + '" in "' + str +
+            '"';
+    }
+    var piece = str.substring(startIndex, endIndex + 1);
+    parts.push(piece);
+    str = str.substring(endIndex + 1);
+  }
+}
+
+/**
  * Fix function specs.
  * The jsdoctoolkit wrongly converts ',' to | as in 'function(a, b)' to
  * 'function(a|b)' and '{id1: type1, id2: type2}' to '{id1: type1|id2: type2}'
  * so we need to put those back here (or fix jsdoctoolkit, the proper solution).
+ * Worse, we have to distinguish between 'function(a|b)' and '(a|b)'. The former
+ * needs to become 'function(a, b)' while the later needs to stay the same.
+ *
  * @param {string} str JSDOC type specification string .
+ * @param {boolean} opt_paren True if we are inside a paren.
  * @return {string} str with '|' converted back to ', ' unless the specification
  *     starts with '(' and ends with ')'. That's not a very good check beacuse
  *     you could 'function((string|number)) and this would fail to do the right
  *     thing.
- *
  */
-function fixSpecCommas(str) {
-  // TODO: This is really a complete hack and we should fix the
-  // jsdoctoolkit.
-  if (startsWith(str, '(') && endsWith(str, ')')) {
-    return str;
+function fixSpecCommas(str, opt_paren) {
+  var start = str.match(g_startContainerRE);
+  if (start) {
+    var startStr = start.toString();
+    var closing = g_openCloseMap[startStr];
+    if (closing) {
+      var lastChar = str[str.length - 1];
+      if (lastChar == closing) {
+        var middle = str.substring(startStr.length, str.length - 1);
+        return startStr +
+          fixSpecCommas(middle, startStr === '(') +
+          lastChar;
+      }
+    }
+  }
+
+  if (str.match(g_containerRE)) {
+    var parts = splitByContainers(str);
+    for (var ii = 0; ii < parts.length; ++ii) {
+      parts[ii] = fixSpecCommas(parts[ii], opt_paren);
+    }
+    return parts.join('');
   } else {
+    if (opt_paren) {
+      return str;
+    }
     return str.replace(/\|/g, ', ');
   }
 }
 
 /**
  * Converts a JSDOC type specification into html links. For example
- * '(!o3djs.math.Vector3|!O3D.math.Vector4)' would change to
+ * '(!o3djs.math.Vector3|!o3djs.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.
@@ -865,7 +925,11 @@ function fixSpecCommas(str) {
 function linkifyTypeSpec(place, str) {
   var output = '';
   if (str) {
-    var fixed = fixSpecCommas(str);
+    try {
+      var fixed = fixSpecCommas(str);
+    } catch (e) {
+      generatePlaceError(place, e);
+    }
     // TODO: needs to split outside of parens and angle brackets.
     if (startsWith(fixed, '(') && endsWith(fixed, ')')) {
       var types = fixed.substring(1, fixed.length - 1).split('|');