Skip to content
Newer
Older
100644 277 lines (197 sloc) 6.36 KB
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
1 Syntax
2 ======
3
4 Comments
5 --------
6
7 Documentation comments start with `/**` and end with `**/`. Each new line starts with `*`.
8
9 /** ...
10 * ...
11 **/
12
13 Tags (optional)
14 ----
15
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
16 The opening line of a comment is reserved for tags. Tags are optional. Tags are separated by a comma followed by optional whitespace(s) (`, `). They can be either a tag name or a key / value pair separated by a colon and optional whitespace(s) (`: `):
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
17
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
18 tagName ': ' tagValue [', ' tagName ': ' tagValue]...
1832e56 @dvv start to elaborate syntax description
dvv authored Nov 28, 2011
19
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
20 Currently supported tags are:
1832e56 @dvv start to elaborate syntax description
dvv authored Nov 28, 2011
21
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
22 * `section: <name>` - description belongs to specified section `name`
23 * `alias of: <name>` - entity is another name for entity `name`
24 * `related to: <name>` - description is related to entity `name`
25 * `read-only` - entity is read-only
26 * `internal` - entity is meant to be private
27 * `chainable` - method can be chained, i.e. the return value is the same object to which method belongs. E.g. $(...).on(...).on(...)
28 * `deprecated` - entity is considered deprecated. Deprecation tag in addition have the following flavors:
29 * `deprecated: <from>` - deprecated starting from version `from`
30 * `deprecated: <from>..<out>` - deprecated starting from version `from` and will be removed by version `out`
31
32 E.g.:
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
33
34 /** deprecated: 1.0..2.0, section: DOM, alias of: Element#descendantOf, chainable
35 * Element#childOf(@element, className) -> Element
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
36 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
37 * ...
38 **/
39
40
41
42 EBNF
43 ----
44
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
45 The lines _directly following_ tags are reserved for the EBNF description of the documented object. Typically, there's only one EBNF per documented object:
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
46
47 /**
48 * Element#down(@element[, cssSelector][, index]) -> Element | null
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
49 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
50 * ...
51 **/
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
52
53 However, methods, functions, etc. may have several signatures, hence may require more than one description line, in which case description lines directly follow each other:
54
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
55 /**
56 * Element#writeAttribute(@element, attribute[, value = true]) -> Element
57 * Element#writeAttribute(@element, attributes) -> Element
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
58 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
59 * ...
60 **/
61
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
62 ## Arguments
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
63
64 For all methods, functions, etc. parentheses around the arguments are required even if no arguments are present.
65 The syntax for arguments is as follows:
66
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
67 ### required arguments
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
68
69 /**
70 * Event.stop(event) -> Event
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
71 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
72 * ...
73 **/
74
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
75 ### optional arguments
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
76
77 Optional arguments are surrounded by squared brackets (`[]`).
78
79 /**
80 * String#evalJSON([sanitize]) -> Object | Array
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
81 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
82 * ...
83 **/
84
85 A default value may be indicated using the equal sign (`=`).
86
87 /**
88 * String#evalJSON([sanitize = false]) -> Object | Array
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
89 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
90 * ...
91 **/
92
93
94 Note that the argument separating comas belong _inside_ the brackets.
95
96 /**
97 * Event.findElement(event[, cssSelector]) -> Element | null
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
98 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
99 * ...
100 **/
101
102 Arguments can be described below the EBNF description using the following syntax:
103
104 - argumentName (acceptedType | otherAcceptedType | ...): description.
105
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
106 ## Supported EBNF types
107
108 **BIG FAT WARNING**: EBNF descriptions **must be separated by an empty comment line** from the rest of description:
109
110 /**
111 * String#evalJSON([sanitize = false]) -> Object | Array
112 *
113 * Here goes markdown for String#evalJSON description.
114 **/
115
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
116
117 /**
118 * Event.findElement(event[, cssSelector]) -> Element | null
119 * - event (Event): a native Event instance
120 * - cssSelector (String): a optional CSS selector which uses
121 * the same syntax found in regular CSS.
122 *
123 * Regular method markdown goes here.
124 **/
125
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
126 ### Namespace
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
127
128 /**
129 * Ajax
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
130 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
131 * ...
132 **/
133
134 /**
135 * Prototype.Browser
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
136 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
137 * ...
138 **/
139
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
140 ### Classes
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
141
142 Classes require a `class` prefix:
143
144 /**
145 * class Ajax.Base
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
146 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
147 * ...
148 **/
149
150 Sub-classes can indicate their parent just like in the Ruby syntax:
151
152 /**
153 * class Ajax.Request < Ajax.Base
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
154 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
155 * ...
156 **/
157
158 Where `Ajax.Base` is the parent class and `Ajax.Request` the subclass.
159
160 Included mixins are indicated like so:
161
162 /**
163 * class CustomHash
164 * includes Enumerable, Comparable
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
165 *
166 * ...
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
167 **/
168
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
169 ### Mixins
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
170
171 Mixins are indicated by a `mixin` prefix:
172
173 /**
174 * mixin Enumerable
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
175 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
176 * ...
177 **/
178
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
179 ### Constructors
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
180
181 Constructors require the `new` prefix and their arguments.
182
183 /**
184 * new Element(tagName[, attributes])
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
185 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
186 * ...
187 **/
188
189 /**
190 * new Foobar()
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
191 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
192 * ...
193 **/
194
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
195 ### Class Methods
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
196
197 Class methods are identified by a dot (`.`).
198
199 /**
200 * Array.from([iterable]) -> Array
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
201 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
202 * ...
203 **/
204
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
205 ### Instance Methods
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
206
207 Instance methods are identified by the hash symbol (`#`).
208
209 /**
210 * Array#first() -> Array element
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
211 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
212 * ...
213 **/
214
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
215 ### Utilities
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
216
217 Utilities are global functions starting with a dollar-sign (`$`).
218
219 /**
220 * $w(string) -> Array
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
221 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
222 * ...
223 **/
224
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
225 ### Methodized Methods
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
226
227 Methodized methods are methods which are both available as a class method and an instance method, in which case the first argument becomes the instance object itself. For example, all of `Element`'s instance methods are methodized and thus also available as class methods of `Element`. Methodized methods are indicated by prefixing their first argument with the `@` symbol.
228
229 /**
230 * Element#hide(@element) -> Element
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
231 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
232 * ...
233 **/
234
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
235 ### Class Properties
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
236
237 Class properties are identified by a dot (`.`).
238
239 /**
240 * Ajax.Responders.responders -> Array
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
241 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
242 * ...
243 **/
244
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
245 ### Instance Properties
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
246
247 Instance properties are identified by the hash symbol (`#`).
248
249 /**
250 * Ajax.Response#responseText -> String
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
251 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
252 * ...
253 **/
254
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
255 ### Constants
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
256
257 Constant must have their value specified using the equal sign (`=`).
258
259 /**
260 * Prototype.JSONFilter = /^\/\*-secure-([\s\S]*)\*\/\s*$/
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
261 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
262 * ...
263 **/
264
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
265 ## Events
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
266
267 Some methods can fire native or custom events. These are indicated below the arguments descriptions:
268
269 /**
270 * Ajax.Request#respondToReadyState(readyState) -> undefined
271 * - readyState (Number): a number from 0 to 4 corresponding to the state of the request.
272 * fires ajax:created, ajax:completed
883a55a @dvv clarified some aspects of syntax
dvv authored Nov 28, 2011
273 *
274 * ...
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored Nov 25, 2011
275 **/
276
Something went wrong with that request. Please try again.