Permalink
Browse files

README update

  • Loading branch information...
1 parent 6766dd8 commit 4087db18c3bab68000c409673e364dcd6eafbf1d @davglass davglass committed Apr 12, 2012
Showing with 21 additions and 121 deletions.
  1. +21 −121 README.md
View
142 README.md
@@ -1,136 +1,36 @@
-[yui-customevents]: http://yuilibrary.com/yui/docs/event-custom/
-[yui-element]: http://developer.yahoo.com/yui/element/
+YUIDoc Doc parser
+=================
-__This is a beta release, the offical release will be under the name `yuidoc`__
+YUIDoc is a [Node.js](http://nodejs.org/) application used at build time to
+generate API documentation for JavaScript code. YUIDoc is comment-driven and supports a wide
+range of JavaScript coding styles. The output of YUI Doc is API documentation formatted as a
+set of HTML pages including information about methods, properties, custom events and
+inheritance for JavaScript objects. YUIDoc was orignally written for the YUI Project;
+it uses YUI JavaScript and CSS in the generated files and it supports common YUI
+conventions like Custom Events. That said, it can be used easily and productively on non-YUI code.
-
-# YUIDoc Doc parser
-
-Updated yuidoc parser, written in js -- *early work in progress*
-
-## Current Build Status
+Current Build Status
+--------------------
[![Build Status](https://secure.travis-ci.org/davglass/yuidocjs.png?branch=master)](http://travis-ci.org/davglass/yuidocjs)
-## Usage
-
-Clone this repo, then:
-
- cd yuidocjs
- npm -g install .
-
- yuidoc /path/to/yui3/src/
- yuidoc /path/to/yui2/src/
- yuidoc ./test/
-
-This will produce a data structure in `out/data.json` by default.
-
-## Code implementation
-
-To log during a build:
-`Y.log("message", "console[method]", "module")`
-
-## Command Line flags
-
- Usage: yuidoc <options> <input path>
-
- Common Options:
- -c, --config, --configfile <filename> A JSON config file to provide configuration data.
- You can also create a yuidoc.json file and place it
- anywhere under your source tree and YUI Doc will find it
- and use it.
- -e, --extension <comma sep list of file extensions> The list of file extensions to parse
- for api documentation. (defaults to .js)
- -x, --exclude <comma sep list of directorues> Directorys to exclude from parsing
- (defaults to '.DS_Store,.svn,CVS,.git,build_rollup_tmp,build_tmp')
- -v, --version Show the current YUIDoc version
- --project-version Set the doc version for the template
- -N, --no-color Turn off terminal colors (for automation)
- -n, --norecurse Do not recurse directories (default is to recurse)
- -S, --selleck Look for Selleck component data and attach to API meta data
- -V, --view Dump the Handlebars.js view data instead of writing template files
- -p, --parse-only Only parse the API docs and create the JSON data, do not render templates
- -o, --out <directory path> Path to put the generated files (defaults to ./out)
- -t, --themedir <directory path> Path to a custom theme directory containing Handlebars templates
- -h, --help Show this help
- -T, --theme <simple|default> Choose one of the built in themes (default is default)
- --server <port> Fire up the YUIDoc server for faster API doc developement. Pass optional port to listen on. (default is 3000)
-
- <input path> Supply a list of paths (shell globbing is handy here)
-
-## Server Mode
-
-YUIDoc can now run at dev time in server mode so that you don't need to render all your API docs to see
-changes as you make them.
-
- yuidoc --server
- or
- yuidoc --server 5000
-
-Then visit:
-
- http://127.0.0.1:3000/
- or
- http://127.0.0.1:5000/
-
-## Commenting Markup Guide
-YUIDoc original Python build - http://developer.yahoo.com/yui/yuidoc/
-(republished here for convenience, if that's ok)
-
-### Primary tags - Each comment block must have one (and only one) of the following tags
-- **module**: There must be one module per source tree. By convention, put your module declaration at the top of the file that contains the main class for your module.
-- **class**: The string identifying the functional class on its parent object; for example, the class for YAHOO.util.Event would be Event (and its @namespace would be "YAHOO.util").
-- **method**: The name of a method on the current class.
-- **event**: In YUI, events are [Custom Events][yui-customevents] fired off programmatically at interesting moments in a component's execution. The event tag is similar to method, but there is no return tag and its params are arguments passed to the event listener.
-- **property**: The name of a property on the current class.
-
-### Secondary tags - After choosing one of the four primary tags, you can further document a module, class, method, event or property with one or more of the following secondary tags.
-- **submodule**: YUI Doc supports the notion that a module is a submodule of a parent module. For example, in YUI 3.x anim-scroll is a submodule of anim. A submodule encompasses a subset of the parent module's functionality. To use submodule designation, provide the parent module's name as the module property and the submodule's name in the submodule property.
-- **namespace**: While it is optional to provide a namespace, it is recommended. This lets you describe your class just with the name: For example, YAHOO.util.Event has a namespace of YAHOO.util and a class of Event.
-- **extends**: Sets up an inheritance relationship between the current class and a parent class; API docs will show and link to items inherited from the parent class.
-- **config**: A config is a managed configuration attribute. In YUI parlance, this is typically an attribute created and managed with the Config class (part of the Container Family).
-- **attribute**: An attribute is a managed configuration attribute. In YUI parlance, this is typically an attribute created and managed with AttributeProvider (part of the [YUI Element Utility][[yui-element]]). An attribute is similar to a config, but YUI Doc will autogenerate documentation for the change events associated with the attribute as provided by Element. (Note: Unless you're using YUI and referring to an attribute managed by AttributeProvider, you should avoid using this tag.)
-- **constructor**: The presence of this tag (which requires no description) indicates that this class is instantiable.
-- **static**: If a class does not have a constructor, then the static tag should be present to signal that it is a static class.
-- **final**: For constants and for read-only configs and attributes.
-- **param**: Defined as @param {type} name description or @param name {type} description, params can be used with classes, methods and events. Use [name] to indicate the param is optional, name* to indicate it is a place holder for 1..n arguments, and [name*] for 0..n arguments.
-- **return**: Defined as @return {type} description.
-- **for**:
-
-Used to define an inner class:
+Installation
+------------
- /**
- * An inner class
- * @class foo
- * @for OuterClass
- */
-
-After the class is done, you need to inform the parser to start working on the outer class again:
+ npm -g i yuidocjs
- /**
- * Another method for the outer class
- * @method bar
- * @for OuterClass
- */
-- **type**: For properties, configs and attributes.
-- **private**: Privates by default are suppressed from the API docs. All methods and properties are assumed to be public unless marked as private.
-- **protected**: Used to designate members that should not be modified by implementers unless they are creating a subclass.
-- **requires**: Used to identify dependencies in the module declaration.
-- **default**: The default value of a property, config or attribute.
-- **uses**: For classes that use YAHOO.lang.augmentProto or YAHOO.lang.augmentObject. Optional method/properties (supplied to augmentProto or augmentObject) are not parsed by YUI Doc.
+Documentation
+-------------
-Example:
+ * [User Guides](http://davglass.github.com/yuidocjs/)
+ * [API Docs](http://davglass.github.com/yuidocjs/api/)
- /**
- * My method description. Like other pieces of your comment blocks,
- * this can span multiple lines.
- * @method methodName
- */
-## Released under the YUI BSD License
+Released under the YUI BSD License
+----------------------------------
-Copyright 2011 Yahoo! Inc.
+Copyright 2012 Yahoo! Inc.
All rights reserved.
Redistribution and use in source and binary forms, with or without

0 comments on commit 4087db1

Please sign in to comment.