Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

added syntax definition, based on tobie/pdoc' one

  • Loading branch information...
commit d3f5bda036129c39b1373785ef1727f561965e7f 1 parent 993db9e
@dvv dvv authored
Showing with 229 additions and 0 deletions.
  1. +229 −0 syntax.md
View
229 syntax.md
@@ -0,0 +1,229 @@
+Syntax
+======
+
+Comments
+--------
+
+Documentation comments start with `/**` and end with `**/`. Each new line starts with `*`.
+
+ /** ...
+ * ...
+ **/
+
+Tags (optional)
+----
+
+The first 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) (`: `).
+
+Currently accepted tags are: `section:`, `alias of: <name>`, `related to:`, `read-only`, `internal`, `chainable`, `deprecated`, `deprecated: <from>`, `deprecated: <from>..<out>`
+
+ /** deprecated: 1.0..2.0, section: DOM, alias of: Element#descendantOf, chainable
+ * Element#childOf(@element, className) -> Element
+ * ...
+ **/
+
+
+
+EBNF
+----
+
+The lines _directly following_ tags are reserved for the EBNF description of the documented object. Typically, there's only one EBNF per documented object. However, some objects might require more than one.
+
+ /**
+ * Element#down(@element[, cssSelector][, index]) -> Element | null
+ * ...
+ **/
+
+ /**
+ * Element#writeAttribute(@element, attribute[, value = true]) -> Element
+ * Element#writeAttribute(@element, attributes) -> Element
+ * ...
+ **/
+
+### Arguments
+
+For all methods, functions, etc. parentheses around the arguments are required even if no arguments are present.
+The syntax for arguments is as follows:
+
+#### required arguments
+
+ /**
+ * Event.stop(event) -> Event
+ * ...
+ **/
+
+#### optional arguments
+
+Optional arguments are surrounded by squared brackets (`[]`).
+
+ /**
+ * String#evalJSON([sanitize]) -> Object | Array
+ * ...
+ **/
+
+A default value may be indicated using the equal sign (`=`).
+
+ /**
+ * String#evalJSON([sanitize = false]) -> Object | Array
+ * ...
+ **/
+
+
+Note that the argument separating comas belong _inside_ the brackets.
+
+ /**
+ * Event.findElement(event[, cssSelector]) -> Element | null
+ * ...
+ **/
+
+Arguments can be described below the EBNF description using the following syntax:
+
+ - argumentName (acceptedType | otherAcceptedType | ...): description.
+
+Argument descriptions **must** be separated by an empty comment line from the rest of description.
+For example:
+
+ /**
+ * Event.findElement(event[, cssSelector]) -> Element | null
+ * - event (Event): a native Event instance
+ * - cssSelector (String): a optional CSS selector which uses
+ * the same syntax found in regular CSS.
+ *
+ * Regular method markdown goes here.
+ **/
+
+### Supported EBNF types
+
+#### Namespace
+
+ /**
+ * Ajax
+ * ...
+ **/
+
+ /**
+ * Prototype.Browser
+ * ...
+ **/
+
+#### Classes
+
+Classes require a `class` prefix:
+
+ /**
+ * class Ajax.Base
+ * ...
+ **/
+
+Sub-classes can indicate their parent just like in the Ruby syntax:
+
+ /**
+ * class Ajax.Request < Ajax.Base
+ * ...
+ **/
+
+Where `Ajax.Base` is the parent class and `Ajax.Request` the subclass.
+
+Included mixins are indicated like so:
+
+ /**
+ * class CustomHash
+ * includes Enumerable, Comparable
+ **/
+
+#### Mixins
+
+Mixins are indicated by a `mixin` prefix:
+
+ /**
+ * mixin Enumerable
+ * ...
+ **/
+
+#### Constructors
+
+Constructors require the `new` prefix and their arguments.
+
+ /**
+ * new Element(tagName[, attributes])
+ * ...
+ **/
+
+ /**
+ * new Foobar()
+ * ...
+ **/
+
+#### Class Methods
+
+Class methods are identified by a dot (`.`).
+
+ /**
+ * Array.from([iterable]) -> Array
+ * ...
+ **/
+
+#### Instance Methods
+
+Instance methods are identified by the hash symbol (`#`).
+
+ /**
+ * Array#first() -> Array element
+ * ...
+ **/
+
+#### Utilities
+
+Utilities are global functions starting with a dollar-sign (`$`).
+
+ /**
+ * $w(string) -> Array
+ * ...
+ **/
+
+#### Methodized Methods
+
+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.
+
+ /**
+ * Element#hide(@element) -> Element
+ * ...
+ **/
+
+#### Class Properties
+
+Class properties are identified by a dot (`.`).
+
+ /**
+ * Ajax.Responders.responders -> Array
+ * ...
+ **/
+
+#### Instance Properties
+
+Instance properties are identified by the hash symbol (`#`).
+
+ /**
+ * Ajax.Response#responseText -> String
+ * ...
+ **/
+
+#### Constants
+
+Constant must have their value specified using the equal sign (`=`).
+
+ /**
+ * Prototype.JSONFilter = /^\/\*-secure-([\s\S]*)\*\/\s*$/
+ * ...
+ **/
+
+### Events
+
+Some methods can fire native or custom events. These are indicated below the arguments descriptions:
+
+ /**
+ * Ajax.Request#respondToReadyState(readyState) -> undefined
+ * - readyState (Number): a number from 0 to 4 corresponding to the state of the request.
+ * fires ajax:created, ajax:completed
+ **/
+
Please sign in to comment.
Something went wrong with that request. Please try again.