@@ -2,7 +2,19 @@ ChangeLog ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Version 0.0.8 (12/05/05, adamoore) +Most recent updates + + Parser: + - Added support for YUI-specific constructs (custom events, + configuration attributes). + - @config generates property info for old Config-style properies + - @attribute generates AttributeProvider docs, and includes the events + that are automatically created. + - Private/protected members are hidden by default. + - Added a flag to support YDN's stat instrumentation + +Version 0.0.8 (12/05/06, adamoore) +------------- - No longer attempts to apply the current namespace to class names in extends, uses, etc. This prevents accidental munging of the name, but requires that the full classname including namespace is used. CHANGES @@ -39,6 +39,15 @@ Get yuidoc: cvs co yahoo/presentation/tools/yuidoc Make a copy of yuidoc/bin/example.sh and modify the paths to suit your needs. +See TAGS for a brief description of the supported tags. Checking out the +source for the YUI library is a good way to get to know how it works. Ex: +http://developer.yahoo.com/yui/docs/Event.js.html + +NOTE: This tool will generally work with code that has been commented for +jsdoc, with one exception: you must have at least one @module block defined +somewhere in your source. If you don't, the program will run but won't +generate anything. + DOS/Windows: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -68,3 +77,11 @@ Get yuidoc: cvs co yahoo/presentation/tools/yuidoc Copy yuidoc\bin\example.bat and modify the paths to suit your needs +See TAGS for a brief description of the supported tags. Checking out the +source for the YUI library is a good way to get to know how it works. Ex: +http://developer.yahoo.com/yui/docs/Event.js.html + +NOTE: This tool will generally work with code that has been commented for +jsdoc, with one exception: you must have at least one @module block defined +somewhere in your source. If you don't, the program will run but won't +generate anything. INSTALL @@ -7,7 +7,7 @@ comment blocks; no attempt is made to understand the javascript itself. The tools are written in python, and should work for version 2.3 and up. To date, it has only been tested in version 2.3 on a unix system. Although -untested, it should work in MS windows as well. +largely untested, it should work in MS windows as well. The following python libraries are required: simplejson - for reading and writing json README @@ -36,6 +36,10 @@ Supported Tags: Include one these blocks in one of your files for your util/widget. The description will appear on the splash page. + NOTE: At least one @module is required. Put one of these near the top + of your source and use it to describe your component. Do not combine + @module with @class. + @namespace YAHOO.namespace While it is optional to provide a namespace, it is recommended. This lets you describe your class just with the name: YAHOO.util.Event -> Event. It only @@ -51,6 +55,10 @@ Supported Tags: @config configName similar to @property, but separates config items from normal properties +@attribute configName + similar to @config, but also auto-generates the [event]Change and + the before[Event]Change events + @method methodName @event @@ -124,11 +132,4 @@ Supported Tags: For classes that use YAHOO.augment The optional method/properties are not supported yet -Tentative list of future tags: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -@instance - A field/method is either @static, @instance, or it belongs to the prototype - - To be included in the module block. Not sure about the syntax. TAGS @@ -1,30 +1,12 @@ yuidoc TODO ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Crosslink and index: copy all module docs into a single directory, - parse out class info from all json files and use to generate the - index, and links that could not be created when docs where generated - outside of this environment. Or the program could accept a series - of output locations and not copy into a single directory. The problem - with this is that we don't know the relative path that needs to be - used for a module. - - Inheritance data for YAHOO.augment - - New comment block types for YAHOO.augment implementations ... - EventPublish and Config. Since these have properties that are not - directly discoverable by the doc tool, and because these properties - can't be accessed like a normal property, we need a way to document - these that describe how they are used. - - Hide private classes and files - - Consider changing the output format to use all arrays instead of - a mix of arrays and dictionaries. For instance, the list of params - has to be an array to keep the order, whereas classes, properties - and methods get sorted so it doesn't matter. Dictionaries are used - when possible because of cross-referencing I needed during the parse, - but this is no doubt more difficult to use than an all array format. + Consider changing the json output format to use all arrays instead of a mix + of arrays and dictionaries. For instance, the list of params has to be an + array to keep the order, whereas classes, properties and methods get sorted + so it doesn't matter. Dictionaries are used when possible because of + cross-referencing I needed during the parse, but this is no doubt more + difficult to use than an all array format. Documentation TODO 4bc457954772a5bff52e22aaa4c7c575365ec103 Adam Moore adamoore@yahoo-inc.com http://github.com/yui/yuidoc/commit/83daf1fa66e108c6f704d19c135818122e07fd85 83daf1fa66e108c6f704d19c135818122e07fd85

2007-10-08T11:42:58-07:00

doc update 8088a46b09bfd61fca518d3d1139efa04eb2bf94 Adam Moore adamoore@yahoo-inc.com