From 198a4cc4264c83a9dfbeb6c000edfbe130dc4001 Mon Sep 17 00:00:00 2001 From: "gman@google.com" Date: Wed, 15 Jul 2009 23:25:13 +0000 Subject: More docs changes. *) Made enums show up *) Right justified return type *) moved class name to right column in summary area *) pretty print code examples *) changed [inherited] to [inhertied from ] *) Changed name in details area to Class.Name or Namespace.Name *) Add subtypes so ParticleEmitter shows up in docs for o3djs.particle *) Grabbed new nixysa so properties show up Review URL: http://codereview.chromium.org/155600 git-svn-id: svn://svn.chromium.org/chrome/trunk/src@20806 0039d316-1c4b-4281-b951-d872f2087c98 --- .../jsdoc-toolkit-templates/class.tmpl | 125 ++++++++++++++++----- .../jsdoc-toolkit-templates/publish.js | 125 +++++++++++++++++++-- .../jsdoc-toolkit-templates/static/header.html | 4 +- .../jsdoc-toolkit-templates/static/prettify.css | 34 ++++++ .../jsdoc-toolkit-templates/static/prettify.js | 23 ++++ .../jsdoc-toolkit-templates/static/stylesheet.css | 8 ++ 6 files changed, 279 insertions(+), 40 deletions(-) create mode 100644 o3d/documentation/jsdoc-toolkit-templates/static/prettify.css create mode 100644 o3d/documentation/jsdoc-toolkit-templates/static/prettify.js (limited to 'o3d/documentation/jsdoc-toolkit-templates') diff --git a/o3d/documentation/jsdoc-toolkit-templates/class.tmpl b/o3d/documentation/jsdoc-toolkit-templates/class.tmpl index 77a8b4f..1f30c40 100644 --- a/o3d/documentation/jsdoc-toolkit-templates/class.tmpl +++ b/o3d/documentation/jsdoc-toolkit-templates/class.tmpl @@ -55,20 +55,49 @@ thisClass = data; + +{! var ownTypes = getPublicTypes(data).sort(makeSortby("name")); + var justEnums = []; + for (var ot = 0; ot < ownTypes.length; ++ot) { + if (isEnum(ownTypes[ot])) { + justEnums.push(ownTypes[ot]); + } + } +!} + +

Public Types

+ + + + + + + +
+ + enum {+property.name+} + + + {+linkifySingleType(makeName('[Type Summary]'), property.memberOf+'.'+property.name)+} + + {+linkifySingleType(makeName('[Type Summary inherit]'), getParentName(property))+}
+
+ + {! var ownMethods = data.methods.sort(makeSortby("name")); !}

Public Member Functions

- +
- - + - + + @@ -77,24 +106,21 @@ thisClass = data; - - {! var ownProperties = data.properties.sort(makeSortby("name")); !} - -

Public Properties

-
  • - <Global> +
    {+linkifyTypeSpec(makeName('[Method Summary]', thisClass.alias, method.name), method.type)+}  {+getQualifiedName(method)+}{+makeSignature(method.params)+}{+method.name+}{+makeSignature(method.params)+}{+linkifySingleType(makeName('[Method Summary inherit]'), getParentName(method))+}
    - - - - - - - - -
  • - <Global>  - {+linkifyTypeSpec(makeName('[Property Summary]', thisClass.alias, property.name), getPropertyType(property))+} - {+getQualifiedName(property)+}
    -
    +{! var ownProperties = getPublicProperties(data).sort(makeSortby("name")); !} + +

    Public Properties

    + + + + + + + + +
    + <Global>  + {+linkifyTypeSpec(makeName('[Property Summary]', thisClass.alias, property.name), getPropertyType(property))+} + {+property.name+}{+linkifySingleType(makeName('[Prop Summary inherit]'), getParentName(property))+}
    @@ -162,6 +188,45 @@ thisClass = data;
    + + + + +
    +

    Public Types Documentation

    + + +
    +
    + + + + +
    {+isEnum(property)?'enum ':''+}{+property.memberOf+"."+property.name+}
    +
    + +
    +

    + {+sanitizeForEZT(property.desc)+} +

    + + +
    See Also: +
      + +
    • + {+linkifyTypeSpec(makeName('[Property See Also]', thisClass.alias), seeAlso)+} +
    • +
      +
    +
    +
    + +
    +
    +
    + +
    @@ -172,11 +237,11 @@ thisClass = data;
    - {! var tempInherited = member.memberOf == thisClass.alias ? "" : "[[]inherited]"; !} + {! var tempInherited = member.memberOf == thisClass.alias ? "" : ("[[]inherited from " + member.memberOf + "]"); !} {! var tempCSS = "memname"; - var tempName = linkifyTypeSpecForReturn(makeName('[Method Detail]', thisClass.alias, member.name), member.type)+" "+getQualifiedName(member); + var tempName = linkifyTypeSpecForReturn(makeName('[Method Detail]', thisClass.alias, member.name), member.type)+" "+getDocName(data, member); var tempParen = "("; var tempEnd = member.params.length > 1 ? "" : ")" !} @@ -187,7 +252,7 @@ thisClass = data; - + {! tempCSS = "paramkey"; @@ -198,7 +263,7 @@ thisClass = data; - + @@ -254,13 +319,14 @@ thisClass = data;

    Member Property Documentation

    -
    {+linkifyTypeSpec(makeName('[Param Detail]', thisClass.alias, member.name, param.name), param.type)+} {+param.name+} ){+tempInherited+}{+tempInherited+}
    {+member.memberOf+"."+member.name+}{+getDocName(data, member)+} (
    - +
    {+linkifyTypeSpec(makeName('[Property Detail]', thisClass.alias, property.name), getPropertyType(property))+} {+getQualifiedName(property)+}{+linkifyTypeSpec(makeName('[Property Detail]', thisClass.alias, property.name), getPropertyType(property))+} {+getDocName(data, property)+} + {+ (property.memberOf == thisClass.alias) ? "" : ("[[]inherited from " + property.memberOf + "]") +} +
    @@ -283,7 +349,6 @@ thisClass = data;
    -
    diff --git a/o3d/documentation/jsdoc-toolkit-templates/publish.js b/o3d/documentation/jsdoc-toolkit-templates/publish.js index 41bdf93..70229a3 100644 --- a/o3d/documentation/jsdoc-toolkit-templates/publish.js +++ b/o3d/documentation/jsdoc-toolkit-templates/publish.js @@ -36,6 +36,7 @@ var g_symbolSet; // so we can look stuff up below. +var g_symbolArray; var g_filePrefix; var g_skipRE; var g_validJSDOCTypes = { @@ -62,6 +63,23 @@ var g_templates = []; * @param {SymbolSet} symbolSet Set of all symbols in all files. */ function publish(symbolSet) { + try { + publishInternal(symbolSet); + } catch (e) { + generateError(e); + } + + if (g_numErrors > 0) { + print('Num Errors: ' + g_numErrors); + System.exit(1); + } +} + +/** + * Called by us to catch errors. + * @param {SymbolSet} symbolSet Set of all symbols in all files. + */ +function publishInternal(symbolSet) { publish.conf = { // trailing slash expected for dirs ext: '.ezt', outDir: JSDOC.opt.d, @@ -106,6 +124,7 @@ function publish(symbolSet) { try { var templatesDir = publish.conf.templatesDir; var classTemplate = new JSDOC.JsPlate(templatesDir + 'class.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'); @@ -124,6 +143,7 @@ function publish(symbolSet) { // get an array version of the symbolset, useful for filtering var symbols = symbolSet.toArray(); + g_symbolArray = symbols; // create the hilited source code files if (false) { @@ -134,6 +154,13 @@ function publish(symbolSet) { } } + // Comment this lines in to see all symbol information. + //for (var ii = 0; ii < symbols.length; ++ii) { + // var symbol = symbols[ii]; + // print('------[' + symbol.name + ']-------------------------------------'); + // dumpObject(symbol, 5); + //} + // get a list of all the classes in the symbolset var classes = symbols.filter(isaClass).sort(makeSortby('alias')); var filteredClasses = []; @@ -156,8 +183,10 @@ function publish(symbolSet) { filteredClasses.push(symbol); // Comment these lines in to see what data is available to the templates. - //print('----------------------------------------------------------------'); - //dumpObject(symbol, 5); + //if (symbol.name == 'Client' || symbol.name == 'particles') { + // print('------[' + symbol.name + ']-----------------------------------'); + // dumpObject(symbol, 5); + //} // symbol.filename symbol.source = symbol.srcFile; // This is used as a link to the source @@ -203,10 +232,8 @@ function publish(symbolSet) { IO.saveFile(publish.conf.outDir, 'namespaces' + publish.conf.ext, namespaces); IO.saveFile(publish.conf.htmlDir, 'namespaces.html', namespaces); - if (g_numErrors > 0) { - print('Num Errors: ' + g_numErrors); - System.exit(1); - } + var exports = exportsTemplate.process(symbols); + IO.saveFile(publish.conf.outDir, 'exports.js', fileList); } /** @@ -458,6 +485,7 @@ function getPropertyType(property) { * @return {string} Sanitized string. */ function sanitizeForEZT(str) { + str = str.replace(/
    /g, '
    ');
       return str.replace(/\[/g, '[[]').replace(/\n\n/g, '

    '); } @@ -769,6 +797,65 @@ function linkifyTypeSpecForReturn(place, str) { } /** + * Check if a symbol is an enum. + * @param {!Symbol} symbol Symbol to check. + * @return {boolean} true if symbol is an enum + */ +function isEnum(symbol) { + if (symbol.isStatic && !symbol.isNamespace) { + if (symbol.comment && symbol.comment.tagTexts) { + for (var ii = 0; ii < symbol.comment.tagTexts.length; ++ii) { + var tag = symbol.comment.tagTexts[ii]; + if (startsWith(tag.toString(), 'enum')) { + return true; + } + } + } + } + return false; +} + +/** + * Gets the public properties of a symbol. + * @param {!Symbol} symbol The symbol to get properties from. + * @return {!Array.} The public properties of the symbol. + */ +function getPublicProperties(symbol) { + var publicProperties = []; + for (var ii = 0; ii < symbol.properties.length; ++ii) { + var property = symbol.properties[ii]; + if (!property.isPrivate && !property.isNamespace && !isEnum(property)) { + publicProperties.push(property); + } + } + return publicProperties; +} + +/** + * Gets the public types of a symbol. + * @param {!Symbol} symbol The symbol to get properties from. + * @return {!Array.} The public types of the symbol. + */ +function getPublicTypes(symbol) { + var publicTypes = []; + for (var ii = 0; ii < symbol.properties.length; ++ii) { + var type = symbol.properties[ii]; + if (!type.isPrivate && !type.isNamespace && isEnum(type)) { + publicTypes.push(type); + } + } + for (var ii = 0; ii < g_symbolArray.length; ++ii) { + var type = g_symbolArray[ii]; + if (type.memberOf == symbol.alias && + !type.isPrivate && + type.is('CONSTRUCTOR')) { + publicTypes.push(type); + } + } + return publicTypes; +} + +/** * Gets a symbol for a type. * This is here mostly for debugging so you can insert a print before or after * each call to g_symbolSet.getSymbol. @@ -791,17 +878,37 @@ function getSourcePath(symbol) { } /** + * Gets the name of the parent of a symbol. + * @param {!Symbol} symbol The symbol to get the parent of + * @return {string} The parent's name. + */ +function getParentName(symbol) { + var parent = getSymbol(symbol.memberOf); + return parent.isNamespace ? symbol.memberOf : parent.name; +} + +/** * 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); + return getParentName(method) + '.' + method.name; +} + +/** + * Gets a Documentation name. For members of a namespace returns the fully + * qualified name. For members of a class returns ClassName.name + * @param {!Symbol} parent Symbol that we are making docs for. + * @param {!Symbol} child Method or property of parent to get doc name for. + * @return {string} Doc name for child. + */ +function getDocName(parent, child) { if (parent.isNamespace) { - return method.memberOf + "." + method.name + return child.memberOf + "." + child.name; } - return parent.name + '.' + method.name; + return parent.name + "." + child.name; } /** diff --git a/o3d/documentation/jsdoc-toolkit-templates/static/header.html b/o3d/documentation/jsdoc-toolkit-templates/static/header.html index b5d9bd6..e06b775 100644 --- a/o3d/documentation/jsdoc-toolkit-templates/static/header.html +++ b/o3d/documentation/jsdoc-toolkit-templates/static/header.html @@ -10,9 +10,11 @@ [#] [#] [#] +[#] +[#] [#] [#] -[#] +[#] [#] [#] [define content_section]#gc-pagecontent[end] [#] [define navigation_section]#gc-toc[end] diff --git a/o3d/documentation/jsdoc-toolkit-templates/static/prettify.css b/o3d/documentation/jsdoc-toolkit-templates/static/prettify.css new file mode 100644 index 0000000..69d11f7 --- /dev/null +++ b/o3d/documentation/jsdoc-toolkit-templates/static/prettify.css @@ -0,0 +1,34 @@ +.str{ color: #008 } +.kwd{ color: #808 } +.com{ color: #800 } +.typ{ color: #606 } +.lit{ color: #066 } +.pun{ color: #660 } +.pln{ color: #060 } +.tag{ color: #008 } +.atn{ color: #606 } +.atv{ color: #080 } +.dec{ color: #606 } +.prettyprint{ + font-family: Fixed, monospace; + font-size: 95%; + margin: 4px 8px 4px 2px; + padding: 4px 6px; + border: 1px solid #CCC; + background-color: #f5f5f5; +} +.re.prettyprint{ +} +@media print { + .str{ color: #060 } + .kwd{ color: #006; font-weight: bold } + .com{ color: #600; font-style: italic } + .typ{ color: #404; font-weight: bold } + .lit{ color: #044 } + .pun{ color: #440 } + .pln{ color: #000 } + .tag{ color: #006;font-weight: bold } + .atn{ color: #404 } + .atv{ color: #060 } +} + diff --git a/o3d/documentation/jsdoc-toolkit-templates/static/prettify.js b/o3d/documentation/jsdoc-toolkit-templates/static/prettify.js new file mode 100644 index 0000000..8fc4c93 --- /dev/null +++ b/o3d/documentation/jsdoc-toolkit-templates/static/prettify.js @@ -0,0 +1,23 @@ +function H(){var x=navigator&&navigator.userAgent&&/\bMSIE 6\./.test(navigator.userAgent);H=function(){return x};return x}(function(){function x(b){b=b.split(/ /g);var a={};for(var c=b.length;--c>=0;){var d=b[c];if(d)a[d]=null}return a}var y="break continue do else for if return while ",U=y+"auto case char const default double enum extern float goto int long register short signed sizeof static struct switch typedef union unsigned void volatile ",D=U+"catch class delete false import new operator private protected public this throw true try ", +I=D+"alignof align_union asm axiom bool concept concept_map const_cast constexpr decltype dynamic_cast explicit export friend inline late_check mutable namespace nullptr reinterpret_cast static_assert static_cast template typeid typename typeof using virtual wchar_t where ",J=D+"boolean byte extends final finally implements import instanceof null native package strictfp super synchronized throws transient ",V=J+"as base by checked decimal delegate descending event fixed foreach from group implicit in interface internal into is lock object out override orderby params readonly ref sbyte sealed stackalloc string select uint ulong unchecked unsafe ushort var ", +K=D+"debugger eval export function get null set undefined var with Infinity NaN ",L="caller delete die do dump elsif eval exit foreach for goto if import last local my next no our print package redo require sub undef unless until use wantarray while BEGIN END ",M=y+"and as assert class def del elif except exec finally from global import in is lambda nonlocal not or pass print raise try with yield False True None ",N=y+"alias and begin case class def defined elsif end ensure false in module next nil not or redo rescue retry self super then true undef unless until when yield BEGIN END ", +O=y+"case done elif esac eval fi function in local set then until ",W=I+V+K+L+M+N+O;function X(b){return b>="a"&&b<="z"||b>="A"&&b<="Z"}function u(b,a,c,d){b.unshift(c,d||0);try{a.splice.apply(a,b)}finally{b.splice(0,2)}}var Y=(function(){var b=["!","!=","!==","#","%","%=","&","&&","&&=","&=","(","*","*=","+=",",","-=","->","/","/=",":","::",";","<","<<","<<=","<=","=","==","===",">",">=",">>",">>=",">>>",">>>=","?","@","[","^","^=","^^","^^=","{","|","|=","||","||=","~","break","case","continue", +"delete","do","else","finally","instanceof","return","throw","try","typeof"],a="(?:(?:(?:^|[^0-9.])\\.{1,3})|(?:(?:^|[^\\+])\\+)|(?:(?:^|[^\\-])-)";for(var c=0;c:&])/g,"\\$1")}a+="|^)\\s*$";return new RegExp(a)})(),P=/&/g,Q=//g,Z=/\"/g;function $(b){return b.replace(P,"&").replace(Q,"<").replace(R,">").replace(Z,""")}function E(b){return b.replace(P,"&").replace(Q,"<").replace(R,">")}var aa= +/</g,ba=/>/g,ca=/'/g,da=/"/g,ea=/&/g,fa=/ /g;function ga(b){var a=b.indexOf("&");if(a<0)return b;for(--a;(a=b.indexOf("&#",a+1))>=0;){var c=b.indexOf(";",a);if(c>=0){var d=b.substring(a+3,c),g=10;if(d&&d.charAt(0)==="x"){d=d.substring(1);g=16}var e=parseInt(d,g);if(!isNaN(e))b=b.substring(0,a)+String.fromCharCode(e)+b.substring(c+1)}}return b.replace(aa,"<").replace(ba,">").replace(ca,"'").replace(da,'"').replace(ea,"&").replace(fa," ")}function S(b){return"XMP"===b.tagName} +function z(b,a){switch(b.nodeType){case 1:var c=b.tagName.toLowerCase();a.push("<",c);for(var d=0;d");for(var e=b.firstChild;e;e=e.nextSibling)z(e,a);if(b.firstChild||!/^(?:br|link|img)$/.test(c))a.push("");break;case 2:a.push(b.name.toLowerCase(),'="',$(b.value),'"');break;case 3:case 4:a.push(E(b.nodeValue));break}}var F=null;function ha(b){if(null===F){var a=document.createElement("PRE"); +a.appendChild(document.createTextNode('\n'));F=!/=0;i-=" ".length)d.push(" ".substring(0,i));g=e+1;break; +case "\n":a=0;break;default:++a}}if(!d)return c;d.push(c.substring(g));return d.join("")}}var ja=/(?:[^<]+|