Various docs fixes.

It turns out we weren't documenting o3djs.math.matrix4
because it was missing an @namespace tag. I tried to
find a way to flag this as an error but as far as can 
tell there, in jsdoctoolkit there is nothing I can use
to distinguish between a function with no parameters
and returns nothing and an un tagged namespace.

In other words

/**
 * no tag here
 */
o3djs.foo.someNamespace = { };

..and..

/**
 * Some func.
 */
o3djs.foo.someFunc = function() { };

Look exactly the same when they get to the doc generation
part of jsdoctoolkit. Both are members of o3djs.foo.
Both have no params and no return type. So I can't tell
that the first one is an error (a non function with no tags)
and the second one is not.

I guess we just have to be vigilant.

Also, a BIG error was I wasn't generated o3djs docs at all
in build_docs.py. Fixed that.

Finally I changed the format some. My opinion was the
summary docs at the top of each module/class were hard
to read so I put them in tables. Will have to check with
Josie once it's checked it now they actually appear on
her test server.

Also made it so for module methods and properties they
get documented as

o3djs.module.method
o3djs.module.property

but for object methods and properties they get documented

ObjectName.method
ObjectName.property

Both used to be documented as just 

method
property

Which I found hard to read since there is no context.



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

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

3 files changed, 88 insertions, 39 deletions

diff --git a/o3d/documentation/build_docs.py b/o3d/documentation/build_docs.py
index 423f246..642b0f0 100755
--- a/o3d/documentation/build_docs.py
+++ b/o3d/documentation/build_docs.py
@@ -137,11 +137,16 @@ def RunNixysa(idl_files, generate, output_dir, nixysa_options):
     idl_files)

 

 

-def RunJSDocToolkit(js_files, output_dir, prefix):

+def RunJSDocToolkit(js_files, output_dir, prefix, o3djs):

   """Executes the JSDocToolkit."""

   list_filename = MakePath('../scons-out/docs/obj/doclist.conf')

   f = open(list_filename, 'w')

-  f.write('{\n_: [\n')

+  f.write('{\nD:{\n')

+  f.write('prefix: "%s",\n' % prefix)

+  f.write('o3djs: "%s",\n' % o3djs)

+  f.write('endMarker: ""\n')

+  f.write('},\n')

+  f.write('_: [\n')

   for filename in js_files:

     f.write('"%s",\n' % filename.replace('\\', '/'))

   f.write(']\n}\n')

@@ -153,7 +158,6 @@ def RunJSDocToolkit(js_files, output_dir, prefix):
     '-jar',

     MakePath('../third_party/jsdoctoolkit/files/jsrun.jar'),

     MakePath('../third_party/jsdoctoolkit/files/app/run.js'),

-    '-D="prefix:%s"' % prefix,

     '-v',

     '-t=%s' % MakePath('./jsdoc-toolkit-templates//'),

     '-d=' + output_dir,

@@ -172,7 +176,11 @@ def BuildJavaScriptForExternsFromIDLs(idl_files, output_dir):
 

 

 def BuildO3DDocsFromJavaScript(js_files, output_dir):

-  RunJSDocToolkit(js_files, output_dir, 'classo3d_1_1_')

+  RunJSDocToolkit(js_files, output_dir, 'classo3d_1_1_', '')

+

+

+def BuildO3DJSDocs(js_files, output_dir):

+  RunJSDocToolkit(js_files, output_dir, 'js_0_1_', 'true')

 

 

 def BuildO3DExternsFile(js_files_dir, extra_externs_file, externs_file):

@@ -213,6 +221,8 @@ def main():
   docs_js_outpath = MakePath('../scons-out/docs/obj/documentation/apijs')

   externs_js_outpath = MakePath('../scons-out/docs/obj/externs')

   o3d_docs_html_outpath = MakePath('../scons-out/docs/obj/documentation/html')

+  o3djs_docs_html_outpath = MakePath(

+      '../scons-out/docs/obj/documentation/html/jsdocs')

   o3d_externs_path = MakePath('../scons-out/docs/obj/o3d-externs.js')

   compiled_o3djs_outpath = MakePath(

       '../scons-out/docs/obj/documentation/base.js')

@@ -242,6 +252,7 @@ def main():
   BuildO3DExternsFile(externs_js_outpath,

                       o3d_extra_externs_path,

                       o3d_externs_path)

+  BuildO3DJSDocs(o3djs_files + [o3d_externs_path], o3djs_docs_html_outpath)

   BuildCompiledO3DJS(o3djs_files,

                      externs_path,

                      o3d_externs_path,

diff --git a/o3d/documentation/jsdoc-toolkit-templates/class.tmpl b/o3d/documentation/jsdoc-toolkit-templates/class.tmpl
index 4ff9bd0..0520705 100644
--- a/o3d/documentation/jsdoc-toolkit-templates/class.tmpl
+++ b/o3d/documentation/jsdoc-toolkit-templates/class.tmpl
@@ -60,17 +60,19 @@ thisClass = data;
   {! var ownMethods = data.methods.sort(makeSortby("name")); !}
   <if test="ownMethods.length">
     <h2>Public Member Functions</h2>
-    <ul>
+    <table>
     <for each="method" in="ownMethods">
     <if test="!method.isPrivate">
-        <li>
-        <if test="method.isStatic||!method.memberOf">&lt;static&gt; </if>
+        <tr><td><li></li></td>
+        <td>
+	<if test="method.isStatic||!method.memberOf">&lt;static&gt; </if>
         <if test="method.type.length">{+linkifyTypeSpec(makeName('[Method Summary]', thisClass.alias, method.name), method.type)+}&nbsp;</if>
-        <a class="el" href="#{+method.name+}">{+method.name+}</a>{+makeSignature(method.params)+}
-        </li>
+	</td>
+	<td><a class="el" href="#{+method.name+}">{+getQualifiedName(method)+}</a>{+makeSignature(method.params)+}</td>
+        </tr>
     </if>
     </for>
-    </ul>
+    </table>
   </if>
 </if>
 
@@ -79,17 +81,19 @@ thisClass = data;
   {! var ownProperties = data.properties.sort(makeSortby("name")); !}
   <if test="ownProperties.length">
     <h2>Public Properties</h2>
-    <ul>
+    <table>
     <for each="property" in="ownProperties">
-    <if test="!property.isPrivate">
-      <li>
+    <if test="!property.isPrivate && !property.isNamespace">
+      <tr><td><li></li></td>
+      <td>
       <if test="property.isStatic||!property.memberOf">&lt;static&gt;&nbsp;</if>
       {+linkifyTypeSpec(makeName('[Property Summary]', thisClass.alias, property.name), getPropertyType(property))+}
-      <a class="el" href="#{+property.name+}">{+property.name+}</a>
-      </li>
+      </td>
+      <td><a class="el" href="#{+property.name+}">{+getQualifiedName(property)+}</a></td>
+      </tr>
     </if>
     </for>
-    </ul>
+    </table>
   </if>
 </if>
 
@@ -172,7 +176,7 @@ thisClass = data;
         <if test="member.params && member.params.length">
         {!
          var tempCSS = "memname";
-         var tempName = linkifyTypeSpecForReturn(makeName('[Method Detail]', thisClass.alias, member.name), member.type)+" "+member.memberOf+"."+member.name;
+         var tempName = linkifyTypeSpecForReturn(makeName('[Method Detail]', thisClass.alias, member.name), member.type)+" "+getQualifiedName(member);
          var tempParen = "(";
          var tempEnd = member.params.length > 1 ? "" : ")"
         !}
@@ -250,13 +254,13 @@ thisClass = data;
   <hr/>
   <h2>Member Property Documentation</h2>
   <for each="property" in="ownProperties">
-  <if test="!property.isPrivate">
+  <if test="!property.isPrivate && !property.isNamespace">
     <a class="anchor" name="{+property.name+}"></a>
     <div class="memitem">
     <div class="memproto">
       <table class="memname">
         <tr>
-          <td class="memname">{+linkifyTypeSpec(makeName('[Property Detail]', thisClass.alias, property.name), getPropertyType(property))+} {+property.memberOf+"."+property.name+}</td>
+          <td class="memname">{+linkifyTypeSpec(makeName('[Property Detail]', thisClass.alias, property.name), getPropertyType(property))+} {+getQualifiedName(property)+}</td>
         </tr>
       </table>
     </div>
diff --git a/o3d/documentation/jsdoc-toolkit-templates/publish.js b/o3d/documentation/jsdoc-toolkit-templates/publish.js
index c461cde..053db6a 100644
--- a/o3d/documentation/jsdoc-toolkit-templates/publish.js
+++ b/o3d/documentation/jsdoc-toolkit-templates/publish.js
@@ -37,6 +37,7 @@
 
 var g_symbolSet;  // so we can look stuff up below.
 var g_filePrefix;
+var g_skipRE;
 var g_validJSDOCTypes = {
   'number': true,
   'Number': true,
@@ -50,6 +51,7 @@ var g_validJSDOCTypes = {
   'undefined': true};
 var g_unknownTypes = { };
 var g_numErrors = 0;
+var g_o3djsMode = false;
 
 /**
  * Called automatically by JsDoc Toolkit.
@@ -61,10 +63,18 @@ function publish(symbolSet) {
     outDir: JSDOC.opt.d || SYS.pwd + '../out/jsdoc/',
     templatesDir: JSDOC.opt.t || SYS.pwd + '../templates/jsdoc/',
     symbolsDir: '',
-    prefix: JSDOC.opt.D.prefix || 'js_1_0_'};
+    prefix: JSDOC.opt.D.prefix || 'js_1_0_',
+    o3djs: JSDOC.opt.D.o3djs || ''};
   publish.conf.srcDir = publish.conf.outDir + 'src/'
   publish.conf.htmlDir = publish.conf.outDir + 'original_html/'
 
+  if (publish.conf.o3djs) {
+    g_o3djsMode = true;
+  }
+
+  // In o3djs mode, don't generate docs for these.
+  g_skipRE = new RegExp('^(o3d$|o3d\\.|Vectormath)');
+
   // 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) {
@@ -127,6 +137,11 @@ function publish(symbolSet) {
     symbol.events = symbol.getEvents();   // 1 order matters
     symbol.methods = symbol.getMethods(); // 2
 
+    if (g_o3djsMode && g_skipRE.test(symbol.alias)) {
+      print('Skipping docs for  : ' + symbol.alias);
+      continue;
+    }
+
     print('Generating docs for: ' + symbol.alias);
     // Comment these lines in to see what data is available to the templates.
     //print('----------------------------------------------------------------');
@@ -180,7 +195,6 @@ function publish(symbolSet) {
   }
 }
 
-
 /**
  *  Gets just the first sentence (up to a full stop).
  *  Should not break on dotted variable names.
@@ -281,19 +295,35 @@ function resolveLinks(str) {
 }
 
 /**
+ * Makes a link for a symbol.
+ * 
+ * @param {string} symbolName Name of symbol 
+ * @param {string} extra extra 
+ * @param {string} opt_bookmark Optional bookmark.
+ */
+function makeSymbolLink(symbolName, extra, opt_bookmark) {
+  var prefix = g_filePrefix;
+  if (g_o3djsMode && g_skipRE.test(symbolName)) {
+    prefix = '../classo3d_1_1_';
+  }
+  return (prefix + symbolName + extra +
+          '.html').toLowerCase() + 
+         (opt_bookmark ? '#' + opt_bookmark : '');
+}
+
+/**
  * Make link from symbol.
  * @param {Object} symbol Symbol from class database.
  * @param {string} opt_extra extra suffix to add before '.html'.
  * @return {string} url to symbol.
  */
 function getLinkToSymbol(symbol, opt_extra) {
+  opt_extra = opt_extra || '_ref';
   if (symbol.is('CONSTRUCTOR') || symbol.isNamespace) {
-    return (g_filePrefix + symbol.alias + (opt_extra || '_ref') +
-            '.html').toLowerCase();
+    return makeSymbolLink(symbol.alias, opt_extra);
   } else {
     var parentSymbol = getSymbol(symbol.memberOf);
-    return (g_filePrefix + parentSymbol.alias + (opt_extra || '_ref') +
-            '.html').toLowerCase() + '#' + symbol.name;
+    return makeSymbolLink(parentSymbol.alias, opt_extra, symbol.name);
   }
 }
 
@@ -632,21 +662,11 @@ function linkifySingleType(place, type) {
           link = '<a class="el" href="' + getLinkToSymbol(symbol) + '#' +
               field + '">' +  type + '</a>';
         } else {
-          if (startsWith(type, 'o3d.')) {
-            // TODO(gman): remove this hack, make nixysa generate JSDOC js
-            //     files instead of C++ headers and pass those into
-            //     jsdoctoolkit.
+          if (subType[0] == '?') {
+            subType = subType.substring(1);
+          }
+          if (!g_validJSDOCTypes[subType]) {
             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);
-            }
           }
         }
       }
@@ -745,3 +765,17 @@ function getSourcePath(symbol) {
   var index = path.indexOf('/o3djs/');
   return path.substring(index + 1);
 }
+
+/**
+ * Gets a qualified name. Used for members. For namespaces will return the fully
+ * qualified name. For objects will return just ObjectName.method
+ * @param {!Symbol} method The method or property to get a qualified name for.
+ * @return {string} The qualified name for the method or property.
+ */
+function getQualifiedName(method) {
+  var parent = getSymbol(method.memberOf);
+  if (parent.isNamespace) {
+    return method.memberOf + "." + method.name
+  }
+  return parent.name + '.' + method.name;
+}