From d9c6e97e8bbe28ba6877a825352ea5ea21a137a7 Mon Sep 17 00:00:00 2001 From: "gman@google.com" Date: Mon, 13 Jul 2009 19:35:01 +0000 Subject: 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 --- o3d/documentation/build_docs.py | 19 ++++-- .../jsdoc-toolkit-templates/class.tmpl | 34 +++++----- .../jsdoc-toolkit-templates/publish.js | 74 ++++++++++++++++------ o3d/samples/o3djs/base.js | 1 + o3d/samples/o3djs/particles.js | 3 + o3d/samples/o3djs/performance.js | 8 ++- 6 files changed, 99 insertions(+), 40 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")); !}

Public Member Functions

-