diff options
Diffstat (limited to 'o3d/documentation/jsdoc-toolkit-templates')
| -rw-r--r-- | o3d/documentation/jsdoc-toolkit-templates/class.tmpl | 34 | ||||
| -rw-r--r-- | o3d/documentation/jsdoc-toolkit-templates/publish.js | 74 |
2 files changed, 73 insertions, 35 deletions
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"><static> </if> + <tr><td><li></li></td> + <td> + <if test="method.isStatic||!method.memberOf"><static> </if> <if test="method.type.length">{+linkifyTypeSpec(makeName('[Method Summary]', thisClass.alias, method.name), method.type)+} </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"><static> </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; +} |