Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 296 lines (210 sloc) 6.961 kb
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
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
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
17
883a55a @dvv clarified some aspects of syntax
dvv authored
18 tagName ': ' tagValue [', ' tagName ': ' tagValue]...
1832e56 @dvv start to elaborate syntax description
dvv authored
19
883a55a @dvv clarified some aspects of syntax
dvv authored
20 Currently supported tags are:
1832e56 @dvv start to elaborate syntax description
dvv authored
21
883a55a @dvv clarified some aspects of syntax
dvv authored
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
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
36 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
37 * ...
38 **/
39
40
41
42 EBNF
43 ----
44
883a55a @dvv clarified some aspects of syntax
dvv authored
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
46
47 /**
48 * Element#down(@element[, cssSelector][, index]) -> Element | null
883a55a @dvv clarified some aspects of syntax
dvv authored
49 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
50 * ...
51 **/
883a55a @dvv clarified some aspects of syntax
dvv authored
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
55 /**
56 * Element#writeAttribute(@element, attribute[, value = true]) -> Element
57 * Element#writeAttribute(@element, attributes) -> Element
883a55a @dvv clarified some aspects of syntax
dvv authored
58 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
59 * ...
60 **/
61
883a55a @dvv clarified some aspects of syntax
dvv authored
62 ## Arguments
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
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
67 ### required arguments
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
68
69 /**
70 * Event.stop(event) -> Event
883a55a @dvv clarified some aspects of syntax
dvv authored
71 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
72 * ...
73 **/
74
883a55a @dvv clarified some aspects of syntax
dvv authored
75 ### optional arguments
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
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
81 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
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
89 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
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
98 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
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
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
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
126 ### Namespace
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
127
128 /**
129 * Ajax
883a55a @dvv clarified some aspects of syntax
dvv authored
130 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
131 * ...
132 **/
133
134 /**
135 * Prototype.Browser
883a55a @dvv clarified some aspects of syntax
dvv authored
136 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
137 * ...
138 **/
139
883a55a @dvv clarified some aspects of syntax
dvv authored
140 ### Classes
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
141
142 Classes require a `class` prefix:
143
144 /**
145 * class Ajax.Base
883a55a @dvv clarified some aspects of syntax
dvv authored
146 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
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
154 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
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
165 *
166 * ...
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
167 **/
168
883a55a @dvv clarified some aspects of syntax
dvv authored
169 ### Mixins
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
170
171 Mixins are indicated by a `mixin` prefix:
172
173 /**
174 * mixin Enumerable
883a55a @dvv clarified some aspects of syntax
dvv authored
175 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
176 * ...
177 **/
178
883a55a @dvv clarified some aspects of syntax
dvv authored
179 ### Constructors
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
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
185 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
186 * ...
187 **/
188
189 /**
190 * new Foobar()
883a55a @dvv clarified some aspects of syntax
dvv authored
191 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
192 * ...
193 **/
194
883a55a @dvv clarified some aspects of syntax
dvv authored
195 ### Class Methods
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
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
201 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
202 * ...
203 **/
204
883a55a @dvv clarified some aspects of syntax
dvv authored
205 ### Instance Methods
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
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
211 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
212 * ...
213 **/
214
883a55a @dvv clarified some aspects of syntax
dvv authored
215 ### Utilities
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
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
221 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
222 * ...
223 **/
224
883a55a @dvv clarified some aspects of syntax
dvv authored
225 ### Methodized Methods
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
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
231 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
232 * ...
233 **/
234
883a55a @dvv clarified some aspects of syntax
dvv authored
235 ### Class Properties
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
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
241 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
242 * ...
243 **/
244
883a55a @dvv clarified some aspects of syntax
dvv authored
245 ### Instance Properties
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
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
251 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
252 * ...
253 **/
254
883a55a @dvv clarified some aspects of syntax
dvv authored
255 ### Constants
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
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
261 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
262 * ...
263 **/
264
883a55a @dvv clarified some aspects of syntax
dvv authored
265 ## Events
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
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
273 *
274 * ...
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
275 **/
276
671a2e2 @dvv some notes in docu
dvv authored
277 Sugar
278 ----
279
280 ## Sections
281
282 Sections are grouped parts of documentation. They don't add to element hierarchy, but just help to organize documentation.
283
284 /**
285 * == Section Name ==
286 *
287 * Describe this section here.
288 **/
289
290 ## Short links
291
292 Short links help to quickly refer some element. Supported are two flavors:
293
294 * `[[HREF]]` - renders to <a href=HREF>HREF</a>
295 * `[[HREF ' ' TEXT]] - renders to <a href=HREF>TEXT</a>
Something went wrong with that request. Please try again.