Fixes a bug in the docs generation for overloaded

functions.

The issue is that JavaScript has no concept of
overloaded functions. Nixysa was merging them
for compilation by the JSCompiler but it needs
to keep them separate for docs.

To fix the issue an option was added to nixysa
to rename overloaded functions with the suffix
xxxOVERLOAD<num>xxx. The docs generators
then remove the suffix where appropriate.

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

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

4 files changed, 32 insertions, 10 deletions

diff --git a/o3d/documentation/build_docs.py b/o3d/documentation/build_docs.py
index ce4d2a1..bf98170 100755
--- a/o3d/documentation/build_docs.py
+++ b/o3d/documentation/build_docs.py
@@ -161,8 +161,10 @@ def DeleteOldDocs(docs_js_outpath):
   except:
     pass
 
+
 def BuildJavaScriptForDocsFromIDLs(idl_files, output_dir):
-  RunNixysa(idl_files, 'jsheader', output_dir, ['--properties-equal-undefined'])
+  RunNixysa(idl_files, 'jsheader', output_dir,
+            ['--properties-equal-undefined', '--overloaded-function-docs'])
 
 
 def BuildJavaScriptForExternsFromIDLs(idl_files, output_dir):
diff --git a/o3d/documentation/jsdoc-toolkit-templates/class.tmpl b/o3d/documentation/jsdoc-toolkit-templates/class.tmpl
index e1865f6..950462b 100644
--- a/o3d/documentation/jsdoc-toolkit-templates/class.tmpl
+++ b/o3d/documentation/jsdoc-toolkit-templates/class.tmpl
@@ -95,7 +95,7 @@ thisClass = data;
         <td class="type">
         <if test="method.type.length">{+linkifyTypeSpec(makeName('[Method Summary]', thisClass.alias, method.name), method.type)+}&nbsp;</if>
         </td>
-        <td><a class="el" href="#{+method.name+}">{+method.name+}</a>{+makeSignature(method.params)+}
+        <td><a class="el" href="#{+method.name+}">{+getNonOverloadedName(method.name)+}</a>{+makeSignature(method.params)+}
           <if test="isDeprecated(method)">
             <span class="deprecated">[[]**DEPRECATED**]</span>
           </if>
diff --git a/o3d/documentation/jsdoc-toolkit-templates/members.tmpl b/o3d/documentation/jsdoc-toolkit-templates/members.tmpl
index 0d5946b..e5f4ed6 100644
--- a/o3d/documentation/jsdoc-toolkit-templates/members.tmpl
+++ b/o3d/documentation/jsdoc-toolkit-templates/members.tmpl
@@ -30,7 +30,7 @@ This is the complete list of members for
   <if test="ownMethods.length">
     <for each="method" in="ownMethods">
     <if test="!method.isPrivate">
-    <tr class="memlist"><td><a class="el" href="{+getLinkToClassByAlias(thisClass.alias)+}#{+method.name+}">{+method.name+}</a>{+ makeSignature(method.params) +}</td><td><a class="el" href="{+getLinkToClassByAlias(method.memberOf)+}">{+method.memberOf+}</a></td><td></td></tr>
+    <tr class="memlist"><td><a class="el" href="{+getLinkToClassByAlias(thisClass.alias)+}#{+method.name+}">{+getNonOverloadedName(method.name)+}</a>{+ makeSignature(method.params) +}</td><td><a class="el" href="{+getLinkToClassByAlias(method.memberOf)+}">{+method.memberOf+}</a></td><td></td></tr>
     </if>
     </for>
   </if>
diff --git a/o3d/documentation/jsdoc-toolkit-templates/publish.js b/o3d/documentation/jsdoc-toolkit-templates/publish.js
index fa990d1..02cc8bb 100644
--- a/o3d/documentation/jsdoc-toolkit-templates/publish.js
+++ b/o3d/documentation/jsdoc-toolkit-templates/publish.js
@@ -66,6 +66,9 @@ var g_templates = [];
 var g_o3dPropertyRE = /^(\w+)\s+(\w+)\s+/;
 var g_startContainerRE = /^(?:function\(|!function\(|[\(<{[])/;
 var g_containerRE = /function\(|!function\(|[\(<{[]/;
+var g_overloadRE = /xxxOVERLOADED\d+xxx/;
+var g_overloadStr = 'xxxOVERLOADED';
+var g_firstOverloadStr = 'xxxOVERLOADED0xxx';
 var g_openCloseMap = {
   'function(': ')',
   '!function(': ')',
@@ -78,6 +81,7 @@ var g_closeMap = {
   '>': true,
   ']': true,
   '}': true};
+var g_symbolsWithoutOverload = {};
 
 /**
  * Called automatically by JsDoc Toolkit.
@@ -818,11 +822,14 @@ function linkifySingleType(place, type) {
         var subType = type.substring(0, period);
         var member = type.substring(period + 1);
         symbol = getSymbol(subType);
-        if (symbol && symbol.hasMember(member)) {
-          var field = type.substring(period + 1);
-          link = '<a class="el" href="' + getLinkToSymbol(symbol) + '#' +
-              field + '">' +  type + '</a>';
-          found = true;
+        if (symbol) {
+          if (symbol.hasMember(member) ||
+              symbol.hasMember(member + g_firstOverloadStr)) {
+            var field = type.substring(period + 1);
+            link = '<a class="el" href="' + getLinkToSymbol(symbol) + '#' +
+                field + '">' +  type + '</a>';
+            found = true;
+          }
         }
       }
 
@@ -1069,6 +1076,19 @@ function getQualifiedName(method) {
 }
 
 /**
+ * Removes the "xxxOVERLOADEDxxx" part of a name
+ * @param {string} name Name that may have a overloaded suffux.
+ * @return {string} The name without the overloaded suffix.
+ */
+function getNonOverloadedName(name) {
+  var index = name.indexOf(g_overloadStr);
+  if (index >= 0) {
+    return name.substring(0, index);
+  }
+  return name;
+}
+
+/**
  * Gets a Documentation name. For members of a namespace returns the fully
  * qualified name. For members of a class returns ClassName.name
  * @param {!Symbol} parent Symbol that we are making docs for.
@@ -1077,9 +1097,9 @@ function getQualifiedName(method) {
  */
 function getDocName(parent, child) {
   if (parent.isNamespace) {
-    return child.memberOf + "." + child.name;
+    return child.memberOf + "." + getNonOverloadedName(child.name);
   }
-  return parent.name + "." + child.name;
+  return parent.name + "." + getNonOverloadedName(child.name);
 }
 
 /**