Added return values to README

1 files changed, 267 insertions, 44 deletions

diff --git a/README.md b/README.md
index 23656a0..a7933de 100644
--- a/README.md
+++ b/README.md
@@ -83,6 +83,8 @@ The main svg.js initializer function creates a root svg node in the given elemen
 var draw = SVG('drawing')
 ```
 
+__`returns`: `SVG.Doc`__
+
 _Javascript inheritance stack: `SVG.Doc` < `SVG.Container` < `SVG.Parent`_
 
 ### Nested svg
@@ -94,6 +96,8 @@ var nested = draw.nested()
 var rect = nested.rect(200, 200)
 ```
 
+__`returns`: `SVG.Nested`__
+
 _Javascript inheritance stack: `SVG.Nested` < `SVG.Container` < `SVG.Parent`_
 
 ### Groups
@@ -110,6 +114,8 @@ Existing elements from the svg document can also be added to a group:
 group.add(rect)
 ```
 
+__`returns`: `SVG.G`__
+
 _Javascript inheritance stack: `SVG.G` < `SVG.Container` < `SVG.Parent`_
 
 ### Hyperlink
@@ -152,6 +158,7 @@ rect.linkTo(function(link) {
 })
 ```
 
+__`returns`: `SVG.A`__
 
 _Javascript inheritance stack: `SVG.A` < `SVG.Container` < `SVG.Parent`_
 
@@ -170,6 +177,8 @@ var defs = rect.doc().defs()
 
 The defs node works exactly the same as groups.
 
+__`returns`: `SVG.Defs`__
+
 _Javascript inheritance stack: `SVG.Defs` < `SVG.Container` < `SVG.Parent`_
 
 
@@ -194,6 +203,8 @@ This will set the `rx` and `ry` attributes to `10`. To set `rx` and `ry` individ
 rect.radius(10, 20)
 ```
 
+__`returns`: `SVG.Rect`__
+
 _Javascript inheritance stack: `SVG.Rect` < `SVG.Shape` < `SVG.Element`_
 
 
@@ -204,6 +215,8 @@ Ellipses, like rects, have two arguments, their `width` and `height`:
 var ellipse = draw.ellipse(200, 100)
 ```
 
+__`returns`: `SVG.Ellipse`__
+
 _Javascript inheritance stack: `SVG.Ellipse` < `SVG.Shape` < `SVG.Element`_
 
 ### Circle
@@ -213,6 +226,8 @@ The only argument necessary for a circle is the diameter:
 var circle = draw.circle(100)
 ```
 
+__`returns`: `SVG.Ellipse`__
+
 _Javascript inheritance stack: `SVG.Ellipse` < `SVG.Shape` < `SVG.Element`_
 
 _Note that this generates an `<ellipse>` element instead of a `<circle>`. This choice has been made to keep the size of the library down._
@@ -230,6 +245,8 @@ Updating a line is done with the `plot()` method:
 line.plot(50, 30, 100, 150)
 ```
 
+__`returns`: `SVG.Line`__
+
 _Javascript inheritance stack: `SVG.Line` < `SVG.Shape` < `SVG.Element`_
 
 ### Polyline
@@ -261,6 +278,8 @@ The `plot()` method can also be animated:
 polyline.animate(3000).plot([[0,0], [100,50], [50,100], [150,50], [200,50], [250,100], [300,50], [350,50]])
 ```
 
+__`returns`: `SVG.Polyline`__
+
 _Javascript inheritance stack: `SVG.Polyline` < `SVG.Shape` < `SVG.Element`_
 
 ### Polygon
@@ -273,6 +292,8 @@ var polygon = draw.polygon('0,0 100,50 50,100').fill('none').stroke({ width: 1 }
 
 Polygon strings are exactly the same as polyline strings. There is no need to close the shape as the first and last point will be connected automatically.
 
+__`returns`: `SVG.Polygon`__
+
 _Javascript inheritance stack: `SVG.Polygon` < `SVG.Shape` < `SVG.Element`_
 
 ### Path
@@ -288,6 +309,8 @@ Paths can be updated using the `plot()` method:
 path.plot('M100,200L300,400')
 ```
 
+__`returns`: `SVG.Path`__
+
 _Javascript inheritance stack: `SVG.Path` < `SVG.Shape` < `SVG.Element`_
 
 For more details on path data strings, please refer to the SVG documentation:
@@ -302,6 +325,8 @@ When creating images the `width` and `height` values should be defined:
 var image = draw.image('/path/to/image.jpg', 200, 200).move(100, 100)
 ```
 
+__`returns`: `SVG.Image`__
+
 _Javascript inheritance stack: `SVG.Image` < `SVG.Shape` < `SVG.Element`_
 
 
@@ -352,6 +377,8 @@ text.font({
 })
 ```
 
+__`returns`: `SVG.Text`__
+
 _Javascript inheritance stack: `SVG.Text` < `SVG.Shape` < `SVG.Element`_
 
 ### TextPath
@@ -392,6 +419,8 @@ Referencing the linked path element directly:
 var path = text.track
 ```
 
+__`returns`: `SVG.TextPath`__
+
 _Javascript inheritance stack: `SVG.TextPath` < `SVG.Element`_
 
 
@@ -412,6 +441,8 @@ var use  = draw.use(rect).move(200, 200)
 
 In this way the rect element acts as a library element. You can edit it but it won't be rendered.
 
+__`returns`: `SVG.Use`__
+
 _Javascript inheritance stack: `SVG.Use` < `SVG.Shape` < `SVG.Element`_
 
 ## Referencing elements
@@ -448,6 +479,7 @@ Every element instance within svg.js has a reference to the actual `node`:
 ```javascript
 element.node
 ```
+__`returns`: node__
 
 ### instance
 Similarly, the node carries a reference to the svg.js `instance`:
@@ -455,6 +487,7 @@ Similarly, the node carries a reference to the svg.js `instance`:
 ```javascript
 node.instance
 ```
+__`returns`: element__
 
 ## Parent reference
 Every element has a reference to its parent:
@@ -465,6 +498,8 @@ Every element has a reference to its parent:
 element.parent
 ```
 
+__`returns`: instance__
+
 Even the main svg document:
 
 ```javascript
@@ -473,6 +508,9 @@ var draw = SVG('drawing')
 draw.parent //-> returns the wrappig html element with id 'drawing'
 ```
 
+__`returns`: node__
+
+
 ### doc()
 For more specific parent filtering the `doc()` method can be used:
 
@@ -496,6 +534,7 @@ rect.doc(SVG.Doc)    //-> returns draw
 rect.doc(SVG.Nested) //-> returns nested
 rect.doc(SVG.G)      //-> returns group
 ```
+__`returns`: element__
 
 ## Child references
 
@@ -505,6 +544,7 @@ To get the first child of a parent element:
 ```javascript
 draw.first()
 ```
+__`returns`: element__
 
 ### last()
 To get the last child of a parent element:
@@ -512,6 +552,7 @@ To get the last child of a parent element:
 ```javascript
 draw.last()
 ```
+__`returns`: element__
 
 ### children()
 An array of all children will can be retreives with the `children` method:
@@ -519,6 +560,7 @@ An array of all children will can be retreives with the `children` method:
 ```javascript
 draw.children()
 ```
+__`returns`: array__
 
 ### each()
 The `each()` allows you to iterate over the all children of a parent element:
@@ -540,6 +582,8 @@ draw.each(function(i, children) {
 
 Note that `this` refers to the current child element.
 
+__`returns`: itself__
+
 ### has()
 Checking the existence of an element within a parent:
 
@@ -550,6 +594,7 @@ var group = draw.group()
 draw.has(rect)  //-> returns true
 group.has(rect) //-> returns false
 ```
+__`returns`: boolean__
 
 ### index()
 Returns the index of given element and retuns -1 when it is not a child:
@@ -561,7 +606,7 @@ var group = draw.group()
 draw.index(rect)  //-> returns 0
 group.index(rect) //-> returns -1
 ```
-__`returns`: a number equal to or higher than `0`, `-1` if not found__
+__`returns`: number__
 
 ### get()
 Get an element on a given position in the children array:
@@ -573,7 +618,7 @@ var circle = draw.circle(50)
 draw.get(0) //-> returns rect
 draw.get(1) //-> returns circle
 ```
-__`returns`: an element__
+__`returns`: element__
 
 ### clear()
 To remove all elements from a parent element:
@@ -619,6 +664,8 @@ Explicitly remove an attribute:
 rect.attr('fill', null)
 ```
 
+__`returns`: value [getter]__
+__`returns`: itself [setter]__
 
 
 ### transform()
@@ -673,6 +720,8 @@ rect.attr('transform', 'matrix(1,0.5,0.5,1,0,0)')
 
 Although that would mean you can't use the `transform()` method because it would overwrite any manually applied transformations. You should only go down this route if you know exactly what you are doing and you want to achieve an effect that is not achievable with the `transform()` method.
 
+__`returns`: number [getter]__
+__`returns`: itself [setter]__
 
 ### style()
 With the `style()` method the `style` attribute can be managed like attributes with `attr`:
@@ -713,6 +762,9 @@ Explicitly deleting individual style definitions works the same as with the `att
 rect.style('cursor', null)
 ```
 
+__`returns`: value [getter]__
+__`returns`: itself [setter]__
+
 
 ### move()
 Move the element to a given `x` and `y` position by its upper left corner:
@@ -738,6 +790,8 @@ rect.attr({ x: 20, y: 60 })
 
 Although `move()` is much more convenient because it will always use the upper left corner as the position reference, whereas with using `attr()` the `x` and `y` reference differ between element types. For example, rect uses the upper left corner with the `x` and `y` attributes, circle and ellipse use their center with the `cx` and `cy` attributes and thereby simply ignoring the `x` and `y` values you might assign.
 
+__`returns`: itself__
+
 ### x()
 Move element only along x-axis by its upper left corner:
 
@@ -751,6 +805,8 @@ Without an argument the `x()` method serves as a getter as well:
 rect.x() //-> returns 200
 ```
 
+__`returns`: number__
+
 ### y()
 Move element only along y-axis by its upper left corner:
 
@@ -764,6 +820,8 @@ Without an argument the `y()` method serves as a getter as well:
 rect.y() //-> returns 350
 ```
 
+__`returns`: number__
+
 ### relative()
 The `move()`, `x()` and `y()` methods move an element to an absolute position. With the `relative()` method, elements can be moved relatively to their current position. This can be done by calling the `relative()` method before the `move()`, `x()` or `y()` methods in the method chain:
 
@@ -775,6 +833,8 @@ This will set the `x` position of the element to `120` and the `y` position to `
 
 It works the same way for `relative().x()` and  `relative().y()`.
 
+__`returns`: object__
+
 
 ### center()
 This is an extra method to move an element by its center:
@@ -792,6 +852,8 @@ rect.center(150, 150, true)
 
 The third argument can be used to center the text element by its anchor point rather than the calculated center position.
 
+__`returns`: itself__
+
 ### cx()
 Move element only along x-axis by its center:
 
@@ -805,6 +867,8 @@ Without an argument the `cx()` method serves as a getter as well:
 rect.cx() //-> returns 200
 ```
 
+__`returns`: number__
+
 ### cy()
 Move element only along y-axis by its center:
 
@@ -818,6 +882,8 @@ Without an argument the `cy()` method serves as a getter as well:
 rect.cy() //-> returns 350
 ```
 
+__`returns`: number__
+
 ### size()
 Set the size of an element by a given `width` and `height`:
 
@@ -839,6 +905,7 @@ rect.size(null, 200)
 
 Same as with `move()` the size of an element could be set by using `attr()`. But because every type of element is handles its size differently the `size()` method is much more convenient.
 
+__`returns`: itself__
 
 ### width()
 Set only width of an element:
@@ -853,6 +920,8 @@ This method also acts as a getter:
 rect.width() //-> returns 200
 ```
 
+__`returns`: number__
+
 ### height()
 Set only height of an element:
 
@@ -866,12 +935,15 @@ This method also acts as a getter:
 rect.height() //-> returns 325
 ```
 
+__`returns`: number__
+
 ### hide()
 Hide element:
 
 ```javascript
 rect.hide()
 ```
+
 __`returns`: itself__
 
 ### show()
@@ -880,6 +952,7 @@ Show element:
 ```javascript
 rect.show()
 ```
+
 __`returns`: itself__
 
 ### visible()
@@ -888,7 +961,8 @@ To check if the element is visible:
 ```javascript
 rect.visible()
 ```
-__`returns`: `true` or `false`__
+
+__`returns`: boolean__
 
 ### clone()
 To make an exact copy of an element the `clone()` method comes in handy:
@@ -896,7 +970,8 @@ To make an exact copy of an element the `clone()` method comes in handy:
 ```javascript
 var clone = rect.clone()
 ```
-__`returns`: a new element__
+
+__`returns`: element__
 
 This will create an new, unlinked copy. If you want to make a linked clone have a look at the [use](#elements/use) element.
 
@@ -906,6 +981,7 @@ Pretty straightforward:
 ```javascript
 rect.remove()
 ```
+
 __`returns`: itself__
 
 ### replace()
@@ -914,7 +990,8 @@ This method will replace the called element with the given element in the same p
 ```javascript
 rect.replace(draw.circle(100))
 ```
-__`returns`: the element passed as argument__
+
+__`returns`: element__
 
 
 ## Inserting elements
@@ -929,6 +1006,8 @@ var group = draw.group()
 group.add(rect) //-> returns group
 ```
 
+__`returns`: itself__
+
 ### put()
 Where the `add()` method returns the parent itself, the `put()` method returns the given element:
 
@@ -936,6 +1015,8 @@ Where the `add()` method returns the parent itself, the `put()` method returns t
 group.put(rect) //-> returns rect
 ```
 
+__`returns`: element__
+
 ### addTo()
 Similarly to the `add()` method on a parent element, elements have the `addTo()` method:
 
@@ -943,6 +1024,8 @@ Similarly to the `add()` method on a parent element, elements have the `addTo()`
 rect.addTo(group) //-> returns rect
 ```
 
+__`returns`: itself__
+
 ### putIn()
 Similarly to the `put()` method on a parent element, elements have the `putIn()` method:
 
@@ -950,6 +1033,7 @@ Similarly to the `put()` method on a parent element, elements have the `putIn()`
 rect.putIn(group) //-> returns group
 ```
 
+__`returns`: element__
 
 ## Geometry
 
@@ -982,6 +1066,9 @@ var zoom = box.zoom
 
 If the size of the viewbox equals the size of the svg drawing, the zoom value will be 1.
 
+__`returns`: `SVG.ViewBox` [getter]__
+__`returns`: itself [setter]__
+
 ### bbox()
 
 ```javascript
@@ -1003,6 +1090,8 @@ var box2 = draw.rect(100,100).move(200,200)
 var box3 = box1.merge(box2)
 ```
 
+__`returns`: `SVG.BBox`__
+
 ### rbox()
 Is similar to `bbox()` but will give you the box around the exact representation of the element, taking all transformations into account.
 
@@ -1010,7 +1099,7 @@ Is similar to `bbox()` but will give you the box around the exact representation
 path.rbox()
 ```
 
-This will return an instance of `SVG.RBox`.
+__`returns`: `SVG.RBox`__
 
 ### inside()
 To check if a given point is inside the bounding box of an element you can use the `inside()` method:
@@ -1024,29 +1113,38 @@ rect.inside(60, 70) //-> returns true
 
 Note: the `x` and `y` positions are tested against the relative position of the element. Any offset on the parent element is not taken into account.
 
+__`returns`: boolean__
+
 
 ## Animating elements
 
-### animate()
-Animating elements is very much the same as manipulating elements, the only difference is you have to include the `animate()` method:
+### Animatable method chain
+Note that the `animate()` method will not return the targeted element but an instance of SVG.FX which will take the following methods:
 
+Of course `attr()`:
 ```javascript
-rect.animate().move(150, 150)
+rect.animate().attr({ fill: '#f03' })
 ```
 
-The `animate()` method will take three arguments. The first is `duration`, the second `ease` and the third `delay`:
-
+The `x()`, `y()` and `move()` methods:
 ```javascript
-rect.animate(2000, '>', 1000).attr({ fill: '#f03' })
+rect.animate().move(100, 100)
 ```
 
-Alternatively you can pass an object as the first argument:
+And the `cx()`, `cy()` and `center()` methods:
+```javascript
+rect.animate().center(200, 200)
+```
 
+If you include the sugar.js module, `fill()`, `stroke()`, `rotate()`, `skew()`, `scale()`, `matrix()`, `opacity()`, `radius()` will be available as well:
 ```javascript
-rect.animate({ ease: '<', delay: 1500 }).attr({ fill: '#f03' })
+rect.animate().rotate(45).skew(25, 0)
 ```
 
-By default `duration` will be set to `1000`, `ease` will be set to `<>`.
+You can also animate non-numeric unit values unsing the `attr()` method:
+```javascript
+rect.attr('x', '10%').animate().attr('x', '50%')
+```
 
 ### easing
 All available ease types are:
@@ -1066,36 +1164,43 @@ function(pos) { return (-Math.cos(pos * Math.PI) / 2) + 0.5 }
 
 For more easing equations, have a look at the [svg.easing.js](https://github.com/wout/svg.easing.js) plugin.
 
-### Animatable method chain
-Note that the `animate()` method will not return the targeted element but an instance of SVG.FX which will take the following methods:
+### animate()
+Animating elements is very much the same as manipulating elements, the only difference is you have to include the `animate()` method:
 
-Of course `attr()`:
 ```javascript
-rect.animate().attr({ fill: '#f03' })
+rect.animate().move(150, 150)
 ```
 
-The `x()`, `y()` and `move()` methods:
-```javascript
-rect.animate().move(100, 100)
-```
+The `animate()` method will take three arguments. The first is `duration`, the second `ease` and the third `delay`:
 
-And the `cx()`, `cy()` and `center()` methods:
 ```javascript
-rect.animate().center(200, 200)
+rect.animate(2000, '>', 1000).attr({ fill: '#f03' })
 ```
 
-If you include the sugar.js module, `fill()`, `stroke()`, `rotate()`, `skew()`, `scale()`, `matrix()` and `opacity()` will be available as well:
+Alternatively you can pass an object as the first argument:
+
 ```javascript
-rect.animate().rotate(45).skew(25, 0)
+rect.animate({ ease: '<', delay: 1500 }).attr({ fill: '#f03' })
 ```
 
-You can also animate non-numeric unit values unsing the `attr()` method:
+By default `duration` will be set to `1000`, `ease` will be set to `<>`.
+
+__`returns`: `SVG.FX`__
+
+
+### pause()
+Pausing an animations is fairly straightforward:
+
 ```javascript
-rect.attr('x', '10%').animate().attr('x', '50%')
+rect.animate().move(200, 200)
+
+rect.mouseenter(function() { this.pause() })
 ```
 
-### pause() and play()
-Pausing and playing an animations is fairly straightforward:
+__`returns`: itself__
+
+### play()
+Will start playing a paused animation:
 
 ```javascript
 rect.animate().move(200, 200)
@@ -1103,6 +1208,7 @@ rect.animate().move(200, 200)
 rect.mouseenter(function() { this.pause() })
 rect.mouseleave(function() { this.play() })
 ```
+__`returns`: itself__
 
 ### stop()
 Animations can be stopped in two ways.
@@ -1123,6 +1229,8 @@ rect.animate().center(200, 200)
 
 Stopping an animation is irreversable.
 
+__`returns`: itself__
+
 ### during()
 If you want to perform your own actions during the animations you can use the `during()` method:
 
@@ -1154,6 +1262,8 @@ rect.animate(3000).move(100, 100).during(function(pos, morph) {
 })
 ```
 
+__`returns`: `SVG.FX`__
+
 ### loop()
 By default the `loop()` method creates and eternal loop:
 
@@ -1167,6 +1277,8 @@ But the loop can also be a predefined number of times:
 rect.animate(3000).move(100, 100).loop(5)
 ```
 
+__`returns`: `SVG.FX`__
+
 ### after()
 Finally, you can add callback methods using `after()`:
 
@@ -1178,6 +1290,8 @@ rect.animate(3000).move(100, 100).after(function() {
 
 Note that the `after()` method will never be called if the animation is looping eternally. 
 
+__`returns`: `SVG.FX`__
+
 ### to()
 Say you want to control the position of an animation with an external event, then the `to()` method will proove very useful:
 
@@ -1193,6 +1307,8 @@ In order to be able use the `to()` method the duration of the animation should b
 
 _This functionality requires the fx.js module which is included in the default distribution._
 
+__`returns`: `SVG.FX`__
+
 
 ## Syntax sugar
 
@@ -1211,6 +1327,8 @@ A single hex string will work as well:
 rect.fill('#f06')
 ```
 
+__`returns`: itself__
+
 ### stroke()
 The `stroke()` method is similar to `fill()`:
 
@@ -1224,6 +1342,8 @@ Like fill, a single hex string will work as well:
 rect.stroke('#f06')
 ```
 
+__`returns`: itself__
+
 ### opacity()
 To set the overall opacity of an element:
 
@@ -1231,6 +1351,8 @@ To set the overall opacity of an element:
 rect.opacity(0.5)
 ```
 
+__`returns`: itself__
+
 ### rotate()
 The `rotate()` method will automatically rotate elements according to the center of the element:
 
@@ -1246,6 +1368,8 @@ Although you can also define a specific rotation point:
 rect.rotate(45, 50, 50)
 ```
 
+__`returns`: itself__
+
 ### skew()
 The `skew()` method will take an `x` and `y` value:
 
@@ -1254,6 +1378,8 @@ The `skew()` method will take an `x` and `y` value:
 rect.skew(0, 45)
 ```
 
+__`returns`: itself__
+
 ### scale()
 The `scale()` method will take an `x` and `y` value:
 
@@ -1262,6 +1388,8 @@ The `scale()` method will take an `x` and `y` value:
 rect.scale(0.5, -1)
 ```
 
+__`returns`: itself__
+
 ### translate()
 The `translate()` method will take an `x` and `y` value:
 
@@ -1285,6 +1413,7 @@ rect.radius(10, 20)
 
 _This functionality requires the sugar.js module which is included in the default distribution._
 
+__`returns`: itself__
 
 
 ## Masking elements
@@ -1298,6 +1427,8 @@ var ellipse = draw.ellipse(80, 40).move(10, 10).fill({ color: '#fff' })
 rect.maskWith(ellipse)
 ```
 
+__`returns`: itself__
+
 ### mask()
 But you can also use multiple elements:
 
@@ -1323,6 +1454,8 @@ var ellipse = draw.ellipse(80, 40).move(10, 10).fill({ color: gradient })
 rect.maskWith(ellipse)
 ```
 
+__`returns`: `SVG.Mask`__
+
 ### unmask()
 Unmasking the elements can be done with the `unmask()` method:
 
@@ -1332,6 +1465,8 @@ rect.unmask()
 
 The `unmask()` method returns the masking element.
 
+__`returns`: itself__
+
 ### remove()
 Removing the mask alltogether will also `unmask()` all masked elements as well:
 
@@ -1339,11 +1474,7 @@ Removing the mask alltogether will also `unmask()` all masked elements as well:
 mask.remove()
 ```
 
-Or:
-
-```javascript
-rect.masker.remove()
-```
+__`returns`: itself__
 
 ### masker
 For your convenience, the masking element is also referenced in the masked element. This can be useful in case you want to change the mask:
@@ -1365,6 +1496,8 @@ var ellipse = draw.ellipse(80, 40).move(10, 10)
 rect.clipWith(ellipse)
 ```
 
+__`returns`: itself__
+
 ### clip()
 Clip multiple elements:
 
@@ -1377,6 +1510,8 @@ var clip = draw.clip().add(text).add(ellipse)
 rect.clipWith(clip)
 ```
 
+__`returns`: `SVG.Clip`__
+
 ### unclip()
 Unclipping the elements can be done with the `unclip()` method:
 
@@ -1384,6 +1519,8 @@ Unclipping the elements can be done with the `unclip()` method:
 rect.unclip()
 ```
 
+__`returns`: itself__
+
 ### remove()
 Removing the clip alltogether will also `unclip()` all clipped elements as well:
 
@@ -1391,11 +1528,7 @@ Removing the clip alltogether will also `unclip()` all clipped elements as well:
 clip.remove()
 ```
 
-Or:
-
-```javascript
-rect.clipper.remove()
-```
+__`returns`: itself__
 
 ### clipper
 For your convenience, the clipping element is also referenced in the clipped element. This can be useful in case you want to change the clipPath:
@@ -1417,6 +1550,8 @@ Move element to the front:
 rect.front()
 ```
 
+__`returns`: itself__
+
 ### back()
 Move element to the back:
 
@@ -1424,6 +1559,8 @@ Move element to the back:
 rect.back()
 ```
 
+__`returns`: itself__
+
 ### forward()
 Move element one step forward:
 
@@ -1431,6 +1568,8 @@ Move element one step forward:
 rect.forward()
 ```
 
+__`returns`: itself__
+
 ### backward()
 Move element one step backward:
 
@@ -1438,6 +1577,8 @@ Move element one step backward:
 rect.backward()
 ```
 
+__`returns`: itself__
+
 ### siblings()
 The arrange.js module brings some additional methods. To get all siblings of rect, including rect itself:
 
@@ -1445,6 +1586,8 @@ The arrange.js module brings some additional methods. To get all siblings of rec
 rect.siblings()
 ```
 
+__`returns`: array__
+
 ### position()
 Get the position (a number) of rect between its siblings:
 
@@ -1452,6 +1595,8 @@ Get the position (a number) of rect between its siblings:
 rect.position()
 ```
 
+__`returns`: number__
+
 ### next()
 Get the next sibling:
 
@@ -1459,6 +1604,8 @@ Get the next sibling:
 rect.next()
 ```
 
+__`returns`: element__
+
 ### previous()
 Get the previous sibling:
 
@@ -1466,6 +1613,8 @@ Get the previous sibling:
 rect.previous()
 ```
 
+__`returns`: element__
+
 ### before()
 Insert an element before another:
 
@@ -1474,6 +1623,8 @@ Insert an element before another:
 rect.before(circle)
 ```
 
+__`returns`: itself__
+
 ### after()
 Insert an element after another:
 
@@ -1482,6 +1633,8 @@ Insert an element after another:
 rect.after(circle)
 ```
 
+__`returns`: itself__
+
 _This functionality requires the arrange.js module which is included in the default distribution._
 
 
@@ -1516,6 +1669,8 @@ Quite a useful feature of sets is the ability to accept multiple elements at onc
 set.add(rect, circle)
 ```
 
+__`returns`: itself__
+
 ### each()
 Iterating over all members in a set is the same as with svg containers:
 
@@ -1527,13 +1682,17 @@ set.each(function(i) {
 
 Note that `this` refers to the current child element.
 
+__`returns`: itself__
+
 ### has()
 Determine if an element is member of the set:
 
 ```javascript
-set.has(rect) //-> returns true of false
+set.has(rect)
 ```
 
+__`returns`: boolean__
+
 ### index()
 Returns the index of a given element in the set.
 
@@ -1541,6 +1700,8 @@ Returns the index of a given element in the set.
 set.index(rect) //-> -1 if element is not a member
 ```
 
+__`returns`: number__
+
 ### get()
 Get the element at a given index:
 
@@ -1548,6 +1709,8 @@ Get the element at a given index:
 set.get(1)
 ```
 
+__`returns`: element__
+
 ### bbox()
 Get the bounding box of all elements in the set:
 
@@ -1555,6 +1718,8 @@ Get the bounding box of all elements in the set:
 set.bbox()
 ```
 
+__`returns`: `SVG.BBox`__
+
 ### remove()
 To remove an element from a set:
 
@@ -1562,6 +1727,8 @@ To remove an element from a set:
 set.remove(rect)
 ```
 
+__`returns`: itself__
+
 ### clear()
 Or to remove all elements from a set:
 
@@ -1569,12 +1736,17 @@ Or to remove all elements from a set:
 set.clear()
 ```
 
+__`returns`: itself__
+
+### animate()
 Sets work with animations as well:
 
 ```javascript
 set.animate(3000).fill('#ff0')
 ```
 
+__`returns`: `SVG.SetFX`__
+
 
 ## Gradients
 
@@ -1588,6 +1760,8 @@ var gradient = draw.gradient('linear', function(stop) {
 })
 ```
 
+__`returns`: `SVG.Gradient`__
+
 ### at()
 The `offset` and `color` parameters are required for stops, `opacity` is optional. Offset is float between 0 and 1, or a percentage value (e.g. `33%`). 
 
@@ -1595,6 +1769,8 @@ The `offset` and `color` parameters are required for stops, `opacity` is optiona
 stop.at({ offset: 0, color: '#333', opacity: 1 })
 ```
 
+__`returns`: itself__
+
 ### from() and to()
 To define the direction you can set from `x`, `y` and to `x`, `y`:
 
@@ -1604,6 +1780,8 @@ gradient.from(0, 0).to(0, 1)
 
 The from and to values are also expressed in percent.
 
+__`returns`: itself__
+
 ### radius()
 Radial gradients have a `radius()` method to define the outermost radius to where the inner color should develop:
 
@@ -1616,6 +1794,8 @@ var gradient = draw.gradient('radial', function(stop) {
 gradient.from(0.5, 0.5).to(0.5, 0.5).radius(0.5)
 ```
 
+__`returns`: itself__
+
 ### update()
 A gradient can also be updated afterwards:
 
@@ -1640,6 +1820,8 @@ draw.gradient('radial', function(stop) {
 s1.update({ offset: 0.1, color: '#0f0', opacity: 1 })
 ```
 
+__`returns`: itself__
+
 ### get()
 The `get()` method makes it even easier to get a stop from an existing gradient:
 
@@ -1653,6 +1835,8 @@ var gradient = draw.gradient('radial', function(stop) {
 var s1 = gradient.get(0) // -> returns "first" stop
 ```
 
+__`returns`: `SVG.Stop`__
+
 ### fill()
 Finally, to use the gradient on an element:
 
@@ -1672,6 +1856,7 @@ gradient.fill() //-> returns 'url(#SvgjsGradient1234)'
 
 _This functionality requires the gradient.js module which is included in the default distribution._
 
+__`returns`: value__
 
 ## Data
 
@@ -1694,6 +1879,8 @@ rect.data({
 })
 ```
 
+__`returns`: itself__
+
 ### Getting
 Fetching the values is similar to the `attr()` method:
 
@@ -1701,6 +1888,8 @@ Fetching the values is similar to the `attr()` method:
 rect.data('key')
 ```
 
+__`returns`: itself__
+
 ### Removing
 Removing the data altogether:
 
@@ -1708,6 +1897,8 @@ Removing the data altogether:
 rect.data('key', null)
 ```
 
+__`returns`: itself__
+
 ### Sustaining data types
 Your values will always be stored as JSON and in some cases this might not be desirable. If you want to store the value as-is, just pass true as the third argument:
 
@@ -1715,6 +1906,8 @@ Your values will always be stored as JSON and in some cases this might not be de
 rect.data('key', 'value', true)
 ```
 
+__`returns`: itself__
+
 
 ## Memory
 
@@ -1740,6 +1933,7 @@ To retrieve a memory
 rect.remember('oldBBox')
 ```
 
+__`returns`: itself__
 
 ### forget()
 Erasing a single memory:
@@ -1761,6 +1955,8 @@ And finally, just erasing the whole memory:
 rect.forget()
 ```
 
+__`returns`: itself__
+
 ## Events
 
 ### Basic events
@@ -1780,6 +1976,8 @@ rect.click(null)
 
 All available evenets are: `click`, `dblclick`, `mousedown`, `mouseup`, `mouseover`, `mouseout`, `mousemove`, `mouseenter` and `mouseleave`.
 
+__`returns`: itself__
+
 ### Event listeners
 
 You can also bind event listeners to elements:
@@ -1792,6 +1990,8 @@ var click = function() {
 rect.on('click', click)
 ```
 
+__`returns`: itself__
+
 Note that the context of event listeners is not the same as events, which are applied directly to the element. Therefore `this` will not refer to the element when using event listeners.
 
 Unbinding events is just as easy:
@@ -1800,6 +2000,8 @@ Unbinding events is just as easy:
 rect.off('click', click)
 ```
 
+__`returns`: itself__
+
 But there is more to event listeners. You can bind events to html elements as well:
 
 ```javascript
@@ -1831,6 +2033,8 @@ Get hex value:
 color.toHex() //-> returns '#ff0066'
 ```
 
+__`returns`: hex color string__
+
 ### toRgb()
 Get rgb string value:
 
@@ -1838,6 +2042,8 @@ Get rgb string value:
 color.toRgb() //-> returns 'rgb(255,0,102)'
 ```
 
+__`returns`: rgb color string__
+
 ### brightness()
 Get the brightness of a color:
 
@@ -1845,6 +2051,10 @@ Get the brightness of a color:
 color.brightness() //-> returns 0.344
 ```
 
+This is the perceived brighness where `0` is black and `1` is white.
+
+__`returns`: number__
+
 ### morph()
 Make a color morphable:
 
@@ -1852,6 +2062,8 @@ Make a color morphable:
 color.morph('#000')
 ```
 
+__`returns`: itself__
+
 ### at()
 Get morphable color at given position:
 
@@ -1860,8 +2072,7 @@ var color = new SVG.Color('#ff0066').morph('#000')
 color.at(0.5).toHex() //-> '#7f0033'
 ```
 
-
-This is the perceived brighness where `0` is black and `1` is white.
+__`returns`: `SVG.Color`__
 
 
 ## Arrays
@@ -1942,6 +2153,8 @@ This method will prepare the array ensuring both the source and destination arra
 
 Note that this method is currently not available on `SVG.PathArray` but will be soon.
 
+__`returns`: itself__
+
 ### at()
 This method will morph the array to a given position between `0` and `1`. Continuing with the previous example:
 
@@ -1951,6 +2164,8 @@ array.at(0.27).toString() //-> returns '27,0 73,100 127,127'
 
 Note that this method is currently not available on `SVG.PathArray` but will be soon.
 
+__`returns`: new instance__
+
 ### settle()
 When morphing is done the `settle()` method will eliminate any transitional points like duplicates:
 
@@ -1960,6 +2175,8 @@ array.settle()
 
 Note that this method is currently not available on `SVG.PathArray` but will be soon.
 
+__`returns`: itself__
+
 ### move()
 Moves geometry of the array with the given `x` and `y` values:
 
@@ -1971,6 +2188,8 @@ array.toString() //-> returns '33,75 133,175'
 
 Note that this method is only available on `SVG.PointArray` and `SVG.PathArray`
 
+__`returns`: itself__
+
 ### size()
 Resizes geometry of the array by the given `width` and `height` values:
 
@@ -1982,6 +2201,8 @@ array.toString() //-> returns '100,100 322,433'
 
 Note that this method is only available on `SVG.PointArray` and `SVG.PathArray`
 
+__`returns`: itself__
+
 ### bbox()
 Gets the bounding box of the geometry of the array:
 
@@ -1991,6 +2212,8 @@ array.bbox()
 
 Note that this method is only available on `SVG.PointArray` and `SVG.PathArray`
 
+__`returns`: object__
+
 
 ## Extending functionality