Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 124 lines (94 sloc) 6.505 kB
1d8cd71 @dtan adding in documentation from the python build
dtan authored
1 [yui-customevents]: http://developer.yahoo.com/yui/event/#customevent
2 [yui-element]: http://developer.yahoo.com/yui/element/
3
f02ec8b @davglass Updated the README with my thoughts
davglass authored
4 # YUIDoc Doc parser
3ebaa95 Initial revision.
Adam Moore authored
5
f02ec8b @davglass Updated the README with my thoughts
davglass authored
6 Updated yuidoc parser, written in js -- *early work in progress*
3ebaa95 Initial revision.
Adam Moore authored
7
f02ec8b @davglass Updated the README with my thoughts
davglass authored
8 ## Usage
28c2785 project,author,icon,url,contributor. timer
Adam Moore authored
9
283ff0c @davglass Added CLI file for npm install
davglass authored
10 Clone this repo, then:
3ebaa95 Initial revision.
Adam Moore authored
11
283ff0c @davglass Added CLI file for npm install
davglass authored
12 cd yuidocjs
e75f96e @davglass Added npm 1.0 '-g' to the README install instructions
davglass authored
13 npm -g install .
283ff0c @davglass Added CLI file for npm install
davglass authored
14
15 yuidoc /path/to/yui3/src/
16 yuidoc /path/to/yui2/src/
17 yuidoc ./test/
3ebaa95 Initial revision.
Adam Moore authored
18
f02ec8b @davglass Updated the README with my thoughts
davglass authored
19 This will produce a data structure in `out/data.json` by default.
3ebaa95 Initial revision.
Adam Moore authored
20
1d8cd71 @dtan adding in documentation from the python build
dtan authored
21 ## Code implementation
22
23 To log during a build:
24 `Y.log("message", "console[method]", "module")`
25
26 ## Command Line flags
27 -c, --config, --configfile Path to your config file, based on ./package.json
28 -e, --extension File extension(s) to search for, defaults to ".js"
29 -x, --exclude
30 -v, --version
31 -n, --norecurse
32 -o, --outdir Directory to output to, defaults to "./out"
33 -t, --themedir A custom theme directory
34
35 ## Commenting Markup Guide
36 YUIDoc original Python build - http://developer.yahoo.com/yui/yuidoc/
37 (republished here for convenience, if that's ok)
38
39 ### Primary tags - Each comment block must have one (and only one) of the following tags
40 - **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.
41 - **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").
42 - **method**: The name of a method on the current class.
43 - **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.
44 - **property**: The name of a property on the current class.
45
46 ### 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.
47 - **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.
48 - **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.
49 - **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.
50 - **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).
51 - **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.)
52 - **constructor**: The presence of this tag (which requires no description) indicates that this class is instantiable.
53 - **static**: If a class does not have a constructor, then the static tag should be present to signal that it is a static class.
54 - **final**: For constants and for read-only configs and attributes.
55 - **param**: Defined as @param {type} name description or @param name {type} description, params can be used with classes, methods and events.
56 - **return**: Defined as @return {type} description.
57 - **for**: Used to define an inner class:
8fc21db @dtan trying to fix formatting
dtan authored
58
1d8cd71 @dtan adding in documentation from the python build
dtan authored
59 /**
60 * An inner class
61 * @class foo
62 * @for OuterClass
63 */
64 After the class is done, you need to inform the parser to start working on the outer class again:
65 /**
66 * Another method for the outer class
67 * @method bar
68 * @for OuterClass
69 */
8fc21db @dtan trying to fix formatting
dtan authored
70
1d8cd71 @dtan adding in documentation from the python build
dtan authored
71 - **type**: For properties, configs and attributes.
72 - **private**: Privates by default are suppressed from the API docs. All methods and properties are assumed to be public unless marked as private.
73 - **protected**: Used to designate members that should not be modified by implementers unless they are creating a subclass.
74 - **requires**: Used to identify dependencies in the module declaration.
75 - **default**: The default value of a property, config or attribute.
76 - **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.
77
8fc21db @dtan trying to fix formatting
dtan authored
78 Example:
1d8cd71 @dtan adding in documentation from the python build
dtan authored
79 /**
80 * My method description. Like other pieces of your comment blocks,
81 * this can span multiple lines.
82 * @method methodName
83 */
f02ec8b @davglass Updated the README with my thoughts
davglass authored
84
85 ## Dav's Thoughts:
86
87 ### Out dir formatting
88
89 Setting up the directory structure like this will help us build a nice templating system on
90 top of this data. It will give us the ability to include just part of the structure. It will
91 also help up when building the new YUILibrary.com site and importing all this data into MongoDB.
92
93 `./out` needs to look like this instead:
94 ./out/
95 data.json //Rollup of all metadata
96 module1/
97 data.json //metadata for only this module
98 module2/
99 data.json
100
28c2785 project,author,icon,url,contributor. timer
Adam Moore authored
101 AM - sounds good -- had in mind a schema system to define different parser outputs, but
102 that might be overkill.
103
f02ec8b @davglass Updated the README with my thoughts
davglass authored
104 ### Parse only what we need to parse.
105
106 Keep a *state* file somewhere that shows the last time this doc tree was parsed
107 This way, we can do a stat on the file to see if it's mtime is greater than the
108 last parse time and only parse it if it is. This will allow us, in the future, to not reparse files
109 that have not changed. It should speed up the parse process for a large file set.
110
9b2a18b .
Adam Moore authored
111 AM - the parse process is super fast. We may want to do this when rendering
112 the templates.
28c2785 project,author,icon,url,contributor. timer
Adam Moore authored
113
f02ec8b @davglass Updated the README with my thoughts
davglass authored
114 ### Module Structure
115
116 I moved docparser into a module of it's own. The YUIDoc module should also be a standalone module.
28c2785 project,author,icon,url,contributor. timer
Adam Moore authored
117 We should make `cli.js` instantiate that class and run it. We also need to add a way to `export`
f02ec8b @davglass Updated the README with my thoughts
davglass authored
118 these modules so they can be *required* in a script and coded against.
28c2785 project,author,icon,url,contributor. timer
Adam Moore authored
119
120 AM - Yep
d5e80aa @evil, @injects
Adam Moore authored
121
122 ### Templates
123
Something went wrong with that request. Please try again.