Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 304 lines (215 sloc) 7.125 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
d332fa2 @puzrin Updated syntax doc
puzrin 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
d332fa2 @puzrin Updated syntax doc
puzrin 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
d332fa2 @puzrin Updated syntax doc
puzrin 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
d332fa2 @puzrin Updated syntax doc
puzrin authored
106 ### Supported EBNF types
883a55a @dvv clarified some aspects of syntax
dvv authored
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 **/
db994b4 @puzrin Version bump. 1.0.5 released
puzrin authored
125
126 Descriptions are parsed as markdown markup, with github-style extension for code blocks
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
127
d332fa2 @puzrin Updated syntax doc
puzrin authored
128 #### Namespace
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
129
130 /**
131 * Ajax
883a55a @dvv clarified some aspects of syntax
dvv authored
132 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
133 * ...
134 **/
135
136 /**
137 * Prototype.Browser
883a55a @dvv clarified some aspects of syntax
dvv authored
138 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
139 * ...
140 **/
141
d332fa2 @puzrin Updated syntax doc
puzrin authored
142 #### Classes
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
143
144 Classes require a `class` prefix:
145
146 /**
147 * class Ajax.Base
883a55a @dvv clarified some aspects of syntax
dvv authored
148 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
149 * ...
150 **/
151
152 Sub-classes can indicate their parent just like in the Ruby syntax:
153
154 /**
155 * class Ajax.Request < Ajax.Base
883a55a @dvv clarified some aspects of syntax
dvv authored
156 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
157 * ...
158 **/
159
160 Where `Ajax.Base` is the parent class and `Ajax.Request` the subclass.
161
162 Included mixins are indicated like so:
163
164 /**
165 * class CustomHash
166 * includes Enumerable, Comparable
883a55a @dvv clarified some aspects of syntax
dvv authored
167 *
168 * ...
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
169 **/
170
d332fa2 @puzrin Updated syntax doc
puzrin authored
171 #### Mixins
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
172
173 Mixins are indicated by a `mixin` prefix:
174
175 /**
176 * mixin Enumerable
883a55a @dvv clarified some aspects of syntax
dvv authored
177 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
178 * ...
179 **/
180
d332fa2 @puzrin Updated syntax doc
puzrin authored
181 #### Constructors
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
182
183 Constructors require the `new` prefix and their arguments.
184
185 /**
186 * new Element(tagName[, attributes])
883a55a @dvv clarified some aspects of syntax
dvv authored
187 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
188 * ...
189 **/
190
191 /**
192 * new Foobar()
883a55a @dvv clarified some aspects of syntax
dvv authored
193 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
194 * ...
195 **/
196
d332fa2 @puzrin Updated syntax doc
puzrin authored
197 #### Class Methods
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
198
199 Class methods are identified by a dot (`.`).
200
201 /**
202 * Array.from([iterable]) -> Array
883a55a @dvv clarified some aspects of syntax
dvv authored
203 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
204 * ...
205 **/
206
d332fa2 @puzrin Updated syntax doc
puzrin authored
207 #### Instance Methods
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
208
209 Instance methods are identified by the hash symbol (`#`).
210
211 /**
212 * Array#first() -> Array element
883a55a @dvv clarified some aspects of syntax
dvv authored
213 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
214 * ...
215 **/
216
d332fa2 @puzrin Updated syntax doc
puzrin authored
217 #### Utilities
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
218
219 Utilities are global functions starting with a dollar-sign (`$`).
220
221 /**
222 * $w(string) -> Array
883a55a @dvv clarified some aspects of syntax
dvv authored
223 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
224 * ...
225 **/
226
d332fa2 @puzrin Updated syntax doc
puzrin authored
227 #### Methodized Methods
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
228
229 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.
230
231 /**
232 * Element#hide(@element) -> Element
883a55a @dvv clarified some aspects of syntax
dvv authored
233 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
234 * ...
235 **/
236
d332fa2 @puzrin Updated syntax doc
puzrin authored
237 #### Class Properties
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
238
239 Class properties are identified by a dot (`.`).
240
241 /**
242 * Ajax.Responders.responders -> Array
883a55a @dvv clarified some aspects of syntax
dvv authored
243 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
244 * ...
245 **/
246
d332fa2 @puzrin Updated syntax doc
puzrin authored
247 #### Instance Properties
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
248
249 Instance properties are identified by the hash symbol (`#`).
250
251 /**
252 * Ajax.Response#responseText -> String
883a55a @dvv clarified some aspects of syntax
dvv authored
253 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
254 * ...
255 **/
256
d332fa2 @puzrin Updated syntax doc
puzrin authored
257 #### Constants
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
258
259 Constant must have their value specified using the equal sign (`=`).
260
261 /**
262 * Prototype.JSONFilter = /^\/\*-secure-([\s\S]*)\*\/\s*$/
883a55a @dvv clarified some aspects of syntax
dvv authored
263 *
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
264 * ...
265 **/
266
a3f3cbc @puzrin Updated docs
puzrin authored
267 #### Events
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
268
a3f3cbc @puzrin Updated docs
puzrin authored
269 Events are identified by `@`:
d3f5bda @dvv added syntax definition, based on tobie/pdoc' one
dvv authored
270
271 /**
a3f3cbc @puzrin Updated docs
puzrin authored
272 * Features@head(request, socket, head)
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
d332fa2 @puzrin Updated syntax doc
puzrin authored
280 ### Sections
671a2e2 @dvv some notes in docu
dvv authored
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
d332fa2 @puzrin Updated syntax doc
puzrin authored
290 ### Short links
671a2e2 @dvv some notes in docu
dvv authored
291
292 Short links help to quickly refer some element. Supported are two flavors:
293
d332fa2 @puzrin Updated syntax doc
puzrin authored
294 * `[[Method.Name]]` - renders to `<a href=HREF>Method.Name</a>`
295 * `[[Method.Name TEXT]]` - renders to `<a href=HREF>TEXT</a>`
296
297 Difference from PDoc
298 --------------------
299
300 1. Descriptions should be ALWAYS separated by empty line from the upper string (signature, section, tags...).
301 2. `deprecated` can have options.
a3f3cbc @puzrin Updated docs
puzrin authored
302 3. Additional tags - read-only, internal, chainable.
303 4. Events support.
Something went wrong with that request. Please try again.