Skip to content
Newer
Older
100644 136 lines (98 sloc) 3.96 KB
34e0cc1 Initial revision
Adam Moore authored
1
2 General Notes:
3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4
5 --General Notes:
6
7 * All comment blocks should have one, and only one, of the following tags:
8 module, class, property, method. If one is not supplied, the parser will
9 complain and the block will likely be skipped.
10
11 * The four block types require a description. This description should appear
12 as the first thing in your comment block.
13
14 /**
15 * My method description. Like other pieces of your comment blocks,
16 * this can span multiple lines.
17 * @method methodName
18 */
19
20 This might work too, but I have not tried it.. I like the other convention:
21
22 /**
23 * @method methodName
24 * @description My method description. Like other pieces of your
25 * comment blocks, this can span multiple lines.
26 */
27
28 * It will warn about any tag that does not contain a description, with the
29 exception of the following: constructor, public, private, static
30
31
32 Supported Tags:
33 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
34
35 @module modulename
36 Include one these blocks in one of your files for your util/widget. The
37 description will appear on the splash page.
38
83daf1f doc update
Adam Moore authored
39 NOTE: At least one @module is required. Put one of these near the top
40 of your source and use it to describe your component. Do not combine
41 @module with @class.
42
34e0cc1 Initial revision
Adam Moore authored
43 @namespace YAHOO.namespace
44 While it is optional to provide a namespace, it is recommended. This lets you
45 describe your class just with the name: YAHOO.util.Event -> Event. It only
46 needs to be included one time as long as this is the first file that is parsed.
47 Probably safer to put it in each file.
48
49 @class ClassName
50
51 @extends YAHOO.namespace.ClassName
52
53 @property propertyName
54
b32b5e2 version 0.0.2
Adam Moore authored
55 @config configName
56 similar to @property, but separates config items from normal properties
57
83daf1f doc update
Adam Moore authored
58 @attribute configName
59 similar to @config, but also auto-generates the [event]Change and
60 the before[Event]Change events
61
34e0cc1 Initial revision
Adam Moore authored
62 @method methodName
63
b32b5e2 version 0.0.2
Adam Moore authored
64 @event
65 similar to @method, but no @return, and the @params define the signature
66 the listeners are executed with.
67
34e0cc1 Initial revision
Adam Moore authored
68 @constructor
69 Only put this if the class can be instantiated
70
71 @static
a257905 0.11.4
Adam Moore authored
72 For classes, methods, properties, etc ...
34e0cc1 Initial revision
Adam Moore authored
73 Probably should have either @constructor or @static in the @class block
74
a257905 0.11.4
Adam Moore authored
75 @final
76 for constants (properties and read-only configs)
77
34e0cc1 Initial revision
Adam Moore authored
78 @param {type} name description -or-
79 @param name {type} description
80 Supported in method blocks or class/constructor blocks.
81
82 @for ClassName
83 Used to define an inner class:
84 /**
85 * An inner class
86 * @class foo
87 * @for OuterClass
88 */
89 After the class is done, you need to inform the parser to start working on
90 the outer class again:
91 /**
92 * Another method for the outer class
93 * @method bar
94 * @for OuterClass
95 */
96
97 @return {type} description
b32b5e2 version 0.0.2
Adam Moore authored
98 for methods
34e0cc1 Initial revision
Adam Moore authored
99
100 @type type
b32b5e2 version 0.0.2
Adam Moore authored
101 for properties and configs
34e0cc1 Initial revision
Adam Moore authored
102
103 @see
104 This is barely supported at this point
105
a257905 0.11.4
Adam Moore authored
106 @deprecated explaination
107 The explaination does not need to be provided, but the parser will warn if
108 you don't. Usually you'll want to say what to use instead
34e0cc1 Initial revision
Adam Moore authored
109
110 @public
111 Allowed to exist as a singular tag, but does nothing. Everthing is assumed
112 public unless marked private
113
b32b5e2 version 0.0.2
Adam Moore authored
114 @private
115 Use to mark that the method/property should not be accessed by implementers
116 (even if it is accessible to them). By default, privates are not present
117 in the api docs.
34e0cc1 Initial revision
Adam Moore authored
118
b32b5e2 version 0.0.2
Adam Moore authored
119 @protected
120 Use to indicate the method/property should not be accessed by implementers
121 unless they are subclassing.
34e0cc1 Initial revision
Adam Moore authored
122
b32b5e2 version 0.0.2
Adam Moore authored
123 @requires module1, module2
124 Supported in the @module declaration. The comma separated list of module
125 short names will eventually be matched against a lookup table when
126 cross-linking is supported
34e0cc1 Initial revision
Adam Moore authored
127
a257905 0.11.4
Adam Moore authored
128 @default
129 The default value of a property or config
130
9c3abc7 Support for version number, beta, experimental, optional
Adam Moore authored
131 @uses YAHOO.namespace.ClassName [method1, method2]
a257905 0.11.4
Adam Moore authored
132 For classes that use YAHOO.augment
133 The optional method/properties are not supported yet
134
34e0cc1 Initial revision
Adam Moore authored
135
Something went wrong with that request. Please try again.