summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rwxr-xr-xo3d/documentation/build_docs.py19
-rw-r--r--o3d/documentation/jsdoc-toolkit-templates/class.tmpl34
-rw-r--r--o3d/documentation/jsdoc-toolkit-templates/publish.js74
-rw-r--r--o3d/samples/o3djs/base.js1
-rw-r--r--o3d/samples/o3djs/particles.js3
-rw-r--r--o3d/samples/o3djs/performance.js8
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")); !}
<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;
+}
diff --git a/o3d/samples/o3djs/base.js b/o3d/samples/o3djs/base.js
index 4807397..ff86e42 100644
--- a/o3d/samples/o3djs/base.js
+++ b/o3d/samples/o3djs/base.js
@@ -648,6 +648,7 @@ o3djs.base.maybeDeobfuscateFunctionName_ = function(name) {
o3djs.base.inherit = function(subClass, superClass) {
/**
* TmpClass.
+ * @ignore
* @constructor
*/
var TmpClass = function() { };
diff --git a/o3d/samples/o3djs/particles.js b/o3d/samples/o3djs/particles.js
index 324d85a..051729f 100644
--- a/o3d/samples/o3djs/particles.js
+++ b/o3d/samples/o3djs/particles.js
@@ -322,6 +322,9 @@ o3djs.particles.createParticleSystem = function(pack,
* else.
* @param {!o3d.ParamFloat} opt_clockParam A ParamFloat to be the default
* clock for emitters of this particle system.
+ * @param {!function(): number} opt_randomFunction A function that returns
+ * a random number between 0.0 and 1.0. This allows you to pass in a
+ * pseudo random function if you need particles that are reproducable.
*/
o3djs.particles.ParticleSystem = function(pack,
viewInfo,
diff --git a/o3d/samples/o3djs/performance.js b/o3d/samples/o3djs/performance.js
index e81396f..92865e5 100644
--- a/o3d/samples/o3djs/performance.js
+++ b/o3d/samples/o3djs/performance.js
@@ -39,6 +39,12 @@
o3djs.provide('o3djs.performance');
/**
+ * A Module to help with adjusting performance.
+ * @namespace
+ */
+o3djs.performance = o3djs.performance || {};
+
+/**
* Creates a utility that monitors performance [in terms of FPS] and helps to
* adjust the rendered scene accordingly.
* @param {number} targetFPSMin the minimum acceptable frame rate; if we're
@@ -155,7 +161,7 @@ o3djs.performance.PerformanceMonitor = function(
* @type {{
* opt_minSamples: number,
* opt_damping: number,
- * opt_delayCycles, number
+ * opt_delayCycles: number
* }}
*/
o3djs.performance.PerformanceMonitor.Options = goog.typedef;
generated by cgit v1.1 at 2025-01-31 16:11:38 +0000