JSCompiler fixes

*) Generate goog.exportSymbol for all o3djs classes,
methods and properties so the JSCompiler does not 
delete them

*) Remove goog.exportSymbol from the compiled result.

*) Remove o3djs.require from the compiled result.

*) Add docs to undocumented items in o3djs.


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

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

4 files changed, 88 insertions, 33 deletions

diff --git a/o3d/documentation/JSCompiler_deploy.jar b/o3d/documentation/JSCompiler_deploy.jar
deleted file mode 100644
index 9f0b4f9..0000000
--- a/o3d/documentation/JSCompiler_deploy.jar
+++ /dev/null
diff --git a/o3d/documentation/build.scons b/o3d/documentation/build.scons
index 1d68f9f..7bc998a 100644
--- a/o3d/documentation/build.scons
+++ b/o3d/documentation/build.scons
@@ -55,24 +55,23 @@ DOCSGEN_ARGS = ['$JSDOC_DIR/build_docs.py $JAVA_EXE']
 
 env["BUILDERS"]["JSDocs"] = Builder(action=env.Python(DOCSGEN_ARGS))
 
-# index.ezt is a file that the jsdoctoolkit happens to build.
-# Putting it in jsdocs means that will be our target dir for the rest
-# of the files.
-env.JSDocs('base.js', LOCAL_JS_SOURCES + LOCAL_IDL_SOURCES +
-           ['$JSDOC_EZT_TEMPLATE_DIR/annotated.tmpl',
-            '$JSDOC_EZT_TEMPLATE_DIR/class.tmpl',
-            '$JSDOC_EZT_TEMPLATE_DIR/classtree.tmpl',
-            '$JSDOC_EZT_TEMPLATE_DIR/filelist.tmpl',
-            '$JSDOC_EZT_TEMPLATE_DIR/members.tmpl',
-            '$JSDOC_EZT_TEMPLATE_DIR/namespaces.tmpl',
-            '$JSDOC_EZT_TEMPLATE_DIR/publish.js',
-            '$JSDOC_EZT_TEMPLATE_DIR/static/header.html',
-            '$JSDOC_EZT_TEMPLATE_DIR/static/footer.html',
-            '$JSDOC_EZT_TEMPLATE_DIR/static/stylesheet.css',
-            '$JSDOC_EZT_TEMPLATE_DIR/static/tabs.css',
-            '$JSDOC_EZT_TEMPLATE_DIR/static/tab_l.gif',
-            '$JSDOC_EZT_TEMPLATE_DIR/static/tab_r.gif',
-            '$JSDOC_EZT_TEMPLATE_DIR/static/tab_b.gif',
-            '$JSDOC_EXTERNS_DIR/externs.js',
-            '$JSDOC_EXTERNS_DIR/o3d-extra-externs.js',
-            '$JSDOC_DIR/build_docs.py'])
+JSCOMP_PATH = "$SCONSTRUCT_DIR/../o3d-internal/jscomp/JSCompiler_deploy.jar"
+if os.path.exists(env.subst(JSCOMP_PATH)):
+  env.JSDocs('base.js', LOCAL_JS_SOURCES + LOCAL_IDL_SOURCES +
+             ['$JSDOC_EZT_TEMPLATE_DIR/annotated.tmpl',
+              '$JSDOC_EZT_TEMPLATE_DIR/class.tmpl',
+              '$JSDOC_EZT_TEMPLATE_DIR/classtree.tmpl',
+              '$JSDOC_EZT_TEMPLATE_DIR/filelist.tmpl',
+              '$JSDOC_EZT_TEMPLATE_DIR/members.tmpl',
+              '$JSDOC_EZT_TEMPLATE_DIR/namespaces.tmpl',
+              '$JSDOC_EZT_TEMPLATE_DIR/publish.js',
+              '$JSDOC_EZT_TEMPLATE_DIR/static/header.html',
+              '$JSDOC_EZT_TEMPLATE_DIR/static/footer.html',
+              '$JSDOC_EZT_TEMPLATE_DIR/static/stylesheet.css',
+              '$JSDOC_EZT_TEMPLATE_DIR/static/tabs.css',
+              '$JSDOC_EZT_TEMPLATE_DIR/static/tab_l.gif',
+              '$JSDOC_EZT_TEMPLATE_DIR/static/tab_r.gif',
+              '$JSDOC_EZT_TEMPLATE_DIR/static/tab_b.gif',
+              '$JSDOC_EXTERNS_DIR/externs.js',
+              '$JSDOC_EXTERNS_DIR/o3d-extra-externs.js',
+              '$JSDOC_DIR/build_docs.py'])
diff --git a/o3d/documentation/build_docs.py b/o3d/documentation/build_docs.py
index d244524..dd995de 100755
--- a/o3d/documentation/build_docs.py
+++ b/o3d/documentation/build_docs.py
@@ -40,6 +40,7 @@ import types
 import glob

 import subprocess

 import shutil

+import re

 

 

 _java_exe = ''

@@ -140,7 +141,7 @@ def RunNixysa(idl_files, generate, output_dir, nixysa_options):
 

 

 def RunJSDocToolkit(js_files, ezt_output_dir, html_output_dir, prefix, mode,

-                    baseURL, topURL):

+                    baseURL, topURL, exports_file):

   """Executes the JSDocToolkit."""

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

   f = open(list_filename, 'w')

@@ -150,6 +151,7 @@ def RunJSDocToolkit(js_files, ezt_output_dir, html_output_dir, prefix, mode,
   f.write('topURL: "%s",\n' % topURL)

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

   f.write('htmlOutDir: "%s",\n' % html_output_dir.replace('\\', '/'))

+  f.write('exportsFile: "%s",\n' % exports_file.replace('\\', '/'))

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

   f.write('},\n')

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

@@ -170,6 +172,10 @@ def RunJSDocToolkit(js_files, ezt_output_dir, html_output_dir, prefix, mode,
     '-c=' + list_filename])

 

 

+def DeleteOldDocs(docs_js_outpath):

+  shutil.rmtree(docs_js_outpath);

+

+

 def BuildJavaScriptForDocsFromIDLs(idl_files, output_dir):

   RunNixysa(idl_files, 'jsheader', output_dir, ['--properties-equal-undefined'])

 

@@ -183,12 +189,12 @@ def BuildJavaScriptForExternsFromIDLs(idl_files, output_dir):
 

 def BuildO3DDocsFromJavaScript(js_files, ezt_output_dir, html_output_dir):

   RunJSDocToolkit(js_files, ezt_output_dir, html_output_dir,

-                  'classo3d_1_1_', 'o3d', '', '')

+                  'classo3d_1_1_', 'o3d', '', '', '')

 

 

-def BuildO3DJSDocs(js_files, ezt_output_dir, html_output_dir):

+def BuildO3DJSDocs(js_files, ezt_output_dir, html_output_dir, exports_file):

   RunJSDocToolkit(js_files, ezt_output_dir, html_output_dir, 'js_0_1_', 'o3djs',

-                  'jsdocs/', '../')

+                  'jsdocs/', '../', exports_file)

 

 

 def BuildO3DExternsFile(js_files_dir, extra_externs_file, externs_file):

@@ -209,7 +215,7 @@ def BuildCompiledO3DJS(o3djs_files,
   Execute([

     _java_exe,

     '-jar',

-    MakePath('JSCompiler_deploy.jar'),

+    MakePath('../../o3d-internal/jscomp/JSCompiler_deploy.jar'),

     '--property_renaming', 'OFF',

     '--variable_renaming', 'LOCAL',

     '--remove_dead_assignments', 'false',

@@ -220,10 +226,11 @@ def BuildCompiledO3DJS(o3djs_files,
     #

     '--collapse_variable_declarations', 'false',

     '--disable_function_inline', 'true',

+    '--noextract_prototype_member_decl', 'true',

     #'--disable_convert_to_dotted_properties', 'true',

     #'--inline_functions', 'false',

     # TODO(gman): Remove the flags below once the compiled js actually works.

-    #'--pretty_print',

+    '--pretty_print',

     #'--print_input_delimiter', 'true',

     #'--strip_whitespace_and_comments_only', 'true',

     ##'--logging_level', '',

@@ -233,6 +240,16 @@ def BuildCompiledO3DJS(o3djs_files,
     ('--js_output_file=%s' % compiled_o3djs_outpath)] +

     ['-js=%s' % (x, ) for x in o3djs_files]);

 

+  # strip out goog.exportSymbol and o3djs.require stuff

+  file = open(compiled_o3djs_outpath, 'r')

+  contents = file.read()

+  file.close()

+  contents = re.sub(r'goog.exportSymbol\([^\)]*\);\n', '', contents)

+  contents = re.sub(r'o3djs.require\([^\)]*\);\n', '', contents)

+  file = open(compiled_o3djs_outpath, 'w')

+  file.write(contents)

+  file.close()

+

 

 def CopyStaticFiles(o3d_docs_ezt_outpath, o3d_docs_html_outpath):

   files = ['stylesheet.css',

@@ -268,6 +285,7 @@ def main():
   o3djs_docs_ezt_outpath = MakePath(docs_outpath + 'reference/jsdocs')

   o3djs_docs_html_outpath = MakePath(docs_outpath + 'local_html/jsdocs')

   o3d_externs_path = MakePath(outpath + 'o3d-externs.js')

+  o3djs_exports_path = MakePath(outpath + 'o3d-exports.js')

   compiled_o3djs_outpath = MakePath(docs_outpath + 'base.js')

   externs_path = MakePath('externs/externs.js')

   o3d_extra_externs_path = MakePath('externs/o3d-extra-externs.js')

@@ -288,6 +306,7 @@ def main():
                        os.path.splitext(os.path.basename(f))[0] + '.js')

                    for f in GlobalsDict['O3D_IDL_SOURCES']]

 

+  DeleteOldDocs(MakePath(docs_outpath))

   BuildJavaScriptForDocsFromIDLs(idl_files, docs_js_outpath)

   BuildO3DDocsFromJavaScript([o3d_extra_externs_path] + docs_js_files,

                              o3d_docs_ezt_outpath, o3d_docs_html_outpath)

@@ -296,9 +315,9 @@ def main():
                       o3d_extra_externs_path,

                       o3d_externs_path)

   BuildO3DJSDocs(o3djs_files + [o3d_externs_path], o3djs_docs_ezt_outpath,

-                 o3djs_docs_html_outpath)

+                 o3djs_docs_html_outpath, o3djs_exports_path)

   CopyStaticFiles(o3d_docs_ezt_outpath, o3d_docs_html_outpath)

-  BuildCompiledO3DJS(o3djs_files,

+  BuildCompiledO3DJS(o3djs_files + [o3djs_exports_path],

                      externs_path,

                      o3d_externs_path,

                      compiled_o3djs_outpath)

diff --git a/o3d/documentation/jsdoc-toolkit-templates/publish.js b/o3d/documentation/jsdoc-toolkit-templates/publish.js
index c588e5a..9070a1a 100644
--- a/o3d/documentation/jsdoc-toolkit-templates/publish.js
+++ b/o3d/documentation/jsdoc-toolkit-templates/publish.js
@@ -85,6 +85,7 @@ function publishInternal(symbolSet) {
     outDir: JSDOC.opt.d,
     templatesDir: JSDOC.opt.t,
     symbolsDir: '',
+    exportsFile: JSDOC.opt.D.exportsFile,
     prefix: JSDOC.opt.D.prefix,
     mode: JSDOC.opt.D.mode};
   publish.conf.srcDir = publish.conf.outDir + 'src/';
@@ -93,6 +94,10 @@ function publishInternal(symbolSet) {
   g_topURL = JSDOC.opt.D.topURL;
   g_outputMode = JSDOC.opt.D.mode;
 
+  for (var key in publish.conf) {
+    print ("publish.conf." + key + ": " + publish.conf[key])
+  }
+
   if (publish.conf.mode == 'o3djs') {
     g_o3djsMode = true;
   }
@@ -100,6 +105,9 @@ function publishInternal(symbolSet) {
   // In o3djs mode, don't generate docs for these.
   g_skipRE = new RegExp('^(o3d$|o3d\\.|Vectormath)');
 
+  // Symbols we should always skip.
+  var alwaysSkipRE = new RegExp('^(_global_|VectorMath|Aos)');
+
   // 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) {
@@ -124,7 +132,7 @@ function publishInternal(symbolSet) {
   try {
     var templatesDir = publish.conf.templatesDir;
     var classTemplate = new JSDOC.JsPlate(templatesDir + 'class.tmpl');
-    //var exportsTemplate = new JSDOC.JsPlate(templatesDir + 'exports.tmpl');
+    var exportsTemplate = new JSDOC.JsPlate(templatesDir + 'exports.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');
@@ -164,6 +172,7 @@ function publishInternal(symbolSet) {
   // get a list of all the classes in the symbolset
   var classes = symbols.filter(isaClass).sort(makeSortby('alias'));
   var filteredClasses = [];
+  var exports = '';
 
   // create each of the class pages
   for (var i = 0, l = classes.length; i < l; i++) {
@@ -173,7 +182,8 @@ function publishInternal(symbolSet) {
     symbol.events = symbol.getEvents();   // 1 order matters
     symbol.methods = symbol.getMethods(); // 2
 
-    if (g_o3djsMode && g_skipRE.test(symbol.alias)) {
+    if ((g_o3djsMode && g_skipRE.test(symbol.alias)) ||
+        alwaysSkipRE.test(symbol.alias)) {
       print('Skipping docs for  : ' + symbol.alias);
       continue;
     }
@@ -214,6 +224,10 @@ function publishInternal(symbolSet) {
                 (publish.conf.prefix + symbol.alias +
                  '_members.html').toLowerCase(),
                 output);
+
+    if (publish.conf.exportsFile) {
+      exports += exportsTemplate.process(symbol);
+    }
   }
 
   var classTree = classTreeTemplate.process(filteredClasses);
@@ -232,8 +246,16 @@ function publishInternal(symbolSet) {
   IO.saveFile(publish.conf.outDir, 'namespaces' + publish.conf.ext, namespaces);
   IO.saveFile(publish.conf.htmlDir, 'namespaces.html', namespaces);
 
-  //var exports = exportsTemplate.process(symbols);
-  //IO.saveFile(publish.conf.outDir, 'exports.js', fileList);
+  if (publish.conf.exportsFile) {
+    print("Writing exports: " + publish.conf.exportsFile);
+    var blankLineRE = /\n *\n/gm;
+    while (blankLineRE.test(exports)) {
+      exports = exports.replace(blankLineRE, '\n');
+    }
+    var parts = publish.conf.exportsFile.replace('\\', '/').
+                match(/(.*?)\/([^\/]+)$/);
+    IO.saveFile(parts[1], parts[2], exports);
+  }
 }
 
 /**
@@ -912,6 +934,21 @@ function getDocName(parent, child) {
 }
 
 /**
+ * Gets a symbol name for export. If the method or property is static returns
+ * "Namespace.Class.method". If not returns "Namespace.Class.prototype.method".
+ * @param {!Symbol} symbol Symbol to get name for.
+ * @return {string} Name of symbol.
+ */
+function getSymbolNameForExport(symbol) {
+  if (!symbol.memberOf) {
+    return symbol.name;
+  }
+  return symbol.memberOf +
+         ((symbol.isStatic || symbol.isNamespace) ? '.' : '.prototype.') +
+         symbol.name;
+}
+
+/**
  * Gets the base URL for links.
  */
 function getBaseURL() {