Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 157 lines (120 sloc) 8.598 kb
cb5439f @lsmith Adding (thin) details about @param formatting
lsmith authored
1 [yui-customevents]: http://yuilibrary.com/yui/docs/event-custom/
1d8cd71 @dtan adding in documentation from the python build
dtan authored
2 [yui-element]: http://developer.yahoo.com/yui/element/
3
071e2ad @davglass README update
davglass authored
4 __This is a beta release, the offical release will be under the name `yuidoc`__
5
6
f02ec8b @davglass Updated the README with my thoughts
davglass authored
7 # YUIDoc Doc parser
3ebaa95 Initial revision.
Adam Moore authored
8
f02ec8b @davglass Updated the README with my thoughts
davglass authored
9 Updated yuidoc parser, written in js -- *early work in progress*
3ebaa95 Initial revision.
Adam Moore authored
10
6766dd8 @davglass Added Build Status
davglass authored
11 ## Current Build Status
12
13 [![Build Status](https://secure.travis-ci.org/davglass/yuidocjs.png?branch=master)](http://travis-ci.org/davglass/yuidocjs)
14
f02ec8b @davglass Updated the README with my thoughts
davglass authored
15 ## Usage
28c2785 project,author,icon,url,contributor. timer
Adam Moore authored
16
283ff0c @davglass Added CLI file for npm install
davglass authored
17 Clone this repo, then:
3ebaa95 Initial revision.
Adam Moore authored
18
283ff0c @davglass Added CLI file for npm install
davglass authored
19 cd yuidocjs
e75f96e @davglass Added npm 1.0 '-g' to the README install instructions
davglass authored
20 npm -g install .
283ff0c @davglass Added CLI file for npm install
davglass authored
21
22 yuidoc /path/to/yui3/src/
23 yuidoc /path/to/yui2/src/
24 yuidoc ./test/
3ebaa95 Initial revision.
Adam Moore authored
25
f02ec8b @davglass Updated the README with my thoughts
davglass authored
26 This will produce a data structure in `out/data.json` by default.
3ebaa95 Initial revision.
Adam Moore authored
27
1d8cd71 @dtan adding in documentation from the python build
dtan authored
28 ## Code implementation
29
30 To log during a build:
31 `Y.log("message", "console[method]", "module")`
32
33 ## Command Line flags
aa755d2 @davglass Fixes #24 - Updated README
davglass authored
34
7945ca3 @davglass README and help updates
davglass authored
35 Usage: yuidoc <options> <input path>
36
37 Common Options:
38 -c, --config, --configfile <filename> A JSON config file to provide configuration data.
39 You can also create a yuidoc.json file and place it
40 anywhere under your source tree and YUI Doc will find it
41 and use it.
42 -e, --extension <comma sep list of file extensions> The list of file extensions to parse
43 for api documentation. (defaults to .js)
44 -x, --exclude <comma sep list of directorues> Directorys to exclude from parsing
45 (defaults to '.DS_Store,.svn,CVS,.git,build_rollup_tmp,build_tmp')
46 -v, --version Show the current YUIDoc version
47 --project-version Set the doc version for the template
48 -N, --no-color Turn off terminal colors (for automation)
49 -n, --norecurse Do not recurse directories (default is to recurse)
50 -S, --selleck Look for Selleck component data and attach to API meta data
51 -V, --view Dump the Handlebars.js view data instead of writing template files
52 -p, --parse-only Only parse the API docs and create the JSON data, do not render templates
53 -o, --out <directory path> Path to put the generated files (defaults to ./out)
54 -t, --themedir <directory path> Path to a custom theme directory containing Handlebars templates
55 -h, --help Show this help
56 -T, --theme <simple|default> Choose one of the built in themes (default is default)
aa755d2 @davglass Fixes #24 - Updated README
davglass authored
57 --server <port> Fire up the YUIDoc server for faster API doc developement. Pass optional port to listen on. (default is 3000)
58
7945ca3 @davglass README and help updates
davglass authored
59 <input path> Supply a list of paths (shell globbing is handy here)
1d8cd71 @dtan adding in documentation from the python build
dtan authored
60
aa755d2 @davglass Fixes #24 - Updated README
davglass authored
61 ## Server Mode
62
63 YUIDoc can now run at dev time in server mode so that you don't need to render all your API docs to see
64 changes as you make them.
65
66 yuidoc --server
67 or
68 yuidoc --server 5000
69
70 Then visit:
71
72 http://127.0.0.1:3000/
73 or
74 http://127.0.0.1:5000/
75
1d8cd71 @dtan adding in documentation from the python build
dtan authored
76 ## Commenting Markup Guide
77 YUIDoc original Python build - http://developer.yahoo.com/yui/yuidoc/
78 (republished here for convenience, if that's ok)
79
80 ### Primary tags - Each comment block must have one (and only one) of the following tags
81 - **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.
82 - **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").
83 - **method**: The name of a method on the current class.
84 - **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.
85 - **property**: The name of a property on the current class.
86
87 ### 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.
88 - **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.
89 - **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.
90 - **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.
91 - **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).
92 - **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.)
93 - **constructor**: The presence of this tag (which requires no description) indicates that this class is instantiable.
94 - **static**: If a class does not have a constructor, then the static tag should be present to signal that it is a static class.
95 - **final**: For constants and for read-only configs and attributes.
cb5439f @lsmith Adding (thin) details about @param formatting
lsmith authored
96 - **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.
1d8cd71 @dtan adding in documentation from the python build
dtan authored
97 - **return**: Defined as @return {type} description.
83dcdb9 @dtan fixing markup
dtan authored
98 - **for**:
99
100 Used to define an inner class:
8fc21db @dtan trying to fix formatting
dtan authored
101
ad6be27 @dtan trying to fix formatting
dtan authored
102 /**
350a6c6 @dtan fixing markup
dtan authored
103 * An inner class
104 * @class foo
105 * @for OuterClass
29e1f73 @dtan trying to fix formatting
dtan authored
106 */
107
108 After the class is done, you need to inform the parser to start working on the outer class again:
109
110 /**
111 * Another method for the outer class
112 * @method bar
113 * @for OuterClass
114 */
8fc21db @dtan trying to fix formatting
dtan authored
115
1d8cd71 @dtan adding in documentation from the python build
dtan authored
116 - **type**: For properties, configs and attributes.
117 - **private**: Privates by default are suppressed from the API docs. All methods and properties are assumed to be public unless marked as private.
118 - **protected**: Used to designate members that should not be modified by implementers unless they are creating a subclass.
119 - **requires**: Used to identify dependencies in the module declaration.
120 - **default**: The default value of a property, config or attribute.
121 - **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.
122
8fc21db @dtan trying to fix formatting
dtan authored
123 Example:
3c44380 @dtan trying to fix formatting
dtan authored
124
1d8cd71 @dtan adding in documentation from the python build
dtan authored
125 /**
29e1f73 @dtan trying to fix formatting
dtan authored
126 * My method description. Like other pieces of your comment blocks,
127 * this can span multiple lines.
128 * @method methodName
129 */
f02ec8b @davglass Updated the README with my thoughts
davglass authored
130
2cdda10 @ericf Updated README to use "YUI BSD" not "YUI BSB" License
ericf authored
131 ## Released under the YUI BSD License
d1429b3 @davglass More License Updates
davglass authored
132
133 Copyright 2011 Yahoo! Inc.
134 All rights reserved.
135
136 Redistribution and use in source and binary forms, with or without
137 modification, are permitted provided that the following conditions are met:
138 * Redistributions of source code must retain the above copyright
139 notice, this list of conditions and the following disclaimer.
140 * Redistributions in binary form must reproduce the above copyright
141 notice, this list of conditions and the following disclaimer in the
142 documentation and/or other materials provided with the distribution.
143 * Neither the name of the Yahoo! Inc. nor the
144 names of its contributors may be used to endorse or promote products
145 derived from this software without specific prior written permission.
146
147 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
148 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
149 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
150 DISCLAIMED. IN NO EVENT SHALL YAHOO! INC. BE LIABLE FOR ANY
151 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
152 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
153 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
154 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
155 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
156 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Something went wrong with that request. Please try again.