From 5d6091fb0a74969830729199ace2c1dbb59374ad Mon Sep 17 00:00:00 2001
From: Mike Sierra <msierra@adobe.com>
Date: Wed, 9 Oct 2013 20:56:44 -0400
Subject: [PATCH] GLOBAL: standardize method descriptions

---
 src/filter.js |  20 ++++----
 src/mina.js   |  22 ++++-----
 src/mouse.js  |  54 +++++++++++-----------
 src/path.js   |  30 ++++++------
 src/set.js    |   8 ++--
 src/svg.js    | 126 +++++++++++++++++++++++++-------------------------
 6 files changed, 130 insertions(+), 130 deletions(-)

diff --git a/src/filter.js b/src/filter.js
index 0ad2e0a..056e1b9 100644
--- a/src/filter.js
+++ b/src/filter.js
@@ -23,7 +23,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Paper.filter
      [ method ]
      **
-     * Creates filter element
+     * Creates a `<filter>` element
      **
      - filstr (string) SVG fragment of filter provided as a string.
      = (object) @Element
@@ -88,7 +88,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Snap.filter.blur
      [ method ]
      **
-     * Returns string of the blur filter.
+     * Returns an SVG markup string for the blur filter
      **
      - x (number) amount of horizontal blur in px.
      - y (number) #optional amount of vertical blur in px.
@@ -115,7 +115,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Snap.filter.shadow
      [ method ]
      **
-     * Returns string of the shadow filter.
+     * Returns an SVG markup string for the shadow filter
      **
      - dx (number) horizontal shift of the shadow in px.
      - dy (number) vertical shift of the shadow in px.
@@ -159,7 +159,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Snap.filter.grayscale
      [ method ]
      **
-     * Returns string of the grayscale filter.
+     * Returns an SVG markup string for the grayscale filter
      **
      - amount (number) amount of filter (`0..1`).
      = (string) filter representation
@@ -186,7 +186,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Snap.filter.sepia
      [ method ]
      **
-     * Returns string of the sepia filter.
+     * Returns an SVG markup string for the sepia filter
      **
      - amount (number) amount of filter (`0..1`).
      = (string) filter representation
@@ -214,7 +214,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Snap.filter.saturate
      [ method ]
      **
-     * Returns string of the saturate filter.
+     * Returns an SVG markup string for the saturate filter
      **
      - amount (number) amount of filter (`0..1`).
      = (string) filter representation
@@ -234,7 +234,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Snap.filter.hueRotate
      [ method ]
      **
-     * Returns string of the hue-rotate filter.
+     * Returns an SVG markup string for the hue-rotate filter
      **
      - angle (number) angle of rotation.
      = (string) filter representation
@@ -252,7 +252,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Snap.filter.invert
      [ method ]
      **
-     * Returns string of the invert filter.
+     * Returns an SVG markup string for the invert filter
      **
      - amount (number) amount of filter (`0..1`).
      = (string) filter representation
@@ -273,7 +273,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Snap.filter.brightness
      [ method ]
      **
-     * Returns string of the brightness filter.
+     * Returns an SVG markup string for the brightness filter
      **
      - amount (number) amount of filter (`0..1`).
      = (string) filter representation
@@ -293,7 +293,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Snap.filter.contrast
      [ method ]
      **
-     * Returns string of the contrast filter.
+     * Returns an SVG markup string for the contrast filter
      **
      - amount (number) amount of filter (`0..1`).
      = (string) filter representation
diff --git a/src/mina.js b/src/mina.js
index 95aaa60..7b3a1ae 100644
--- a/src/mina.js
+++ b/src/mina.js
@@ -127,7 +127,7 @@ var mina = (function (eve) {
      * mina
      [ method ]
      **
-     * Generic animation of numbers.
+     * Generic animation of numbers
      **
      - a (number) start _slave_ number
      - A (number) end _slave_ number
@@ -188,7 +188,7 @@ var mina = (function (eve) {
      * mina.time
      [ method ]
      **
-     * Returns current time. Equal to
+     * Returns the current time. Equivalent to:
      | function () {
      |     return (new Date).getTime();
      | }
@@ -198,7 +198,7 @@ var mina = (function (eve) {
      * mina.getById
      [ method ]
      **
-     * Returns animation by its id.
+     * Returns an animation by its id
      - id (string) animation's id
      = (object) See @mina
     \*/
@@ -210,7 +210,7 @@ var mina = (function (eve) {
      * mina.linear
      [ method ]
      **
-     * Default linear easing.
+     * Default linear easing
      - n (number) input 0..1
      = (number) output 0..1
     \*/
@@ -221,7 +221,7 @@ var mina = (function (eve) {
      * mina.easeout
      [ method ]
      **
-     * Easeout easing.
+     * Easeout easing
      - n (number) input 0..1
      = (number) output 0..1
     \*/
@@ -232,7 +232,7 @@ var mina = (function (eve) {
      * mina.easein
      [ method ]
      **
-     * Easein easing.
+     * Easein easing
      - n (number) input 0..1
      = (number) output 0..1
     \*/
@@ -243,7 +243,7 @@ var mina = (function (eve) {
      * mina.easeinout
      [ method ]
      **
-     * Easeinout easing.
+     * Easeinout easing
      - n (number) input 0..1
      = (number) output 0..1
     \*/
@@ -267,7 +267,7 @@ var mina = (function (eve) {
      * mina.backin
      [ method ]
      **
-     * Backin easing.
+     * Backin easing
      - n (number) input 0..1
      = (number) output 0..1
     \*/
@@ -282,7 +282,7 @@ var mina = (function (eve) {
      * mina.backout
      [ method ]
      **
-     * Backout easing.
+     * Backout easing
      - n (number) input 0..1
      = (number) output 0..1
     \*/
@@ -298,7 +298,7 @@ var mina = (function (eve) {
      * mina.elastic
      [ method ]
      **
-     * Elastic easing.
+     * Elastic easing
      - n (number) input 0..1
      = (number) output 0..1
     \*/
@@ -313,7 +313,7 @@ var mina = (function (eve) {
      * mina.bounce
      [ method ]
      **
-     * Bounce easing.
+     * Bounce easing
      - n (number) input 0..1
      = (number) output 0..1
     \*/
diff --git a/src/mouse.js b/src/mouse.js
index 4821899..a52cff5 100644
--- a/src/mouse.js
+++ b/src/mouse.js
@@ -148,7 +148,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.click
      [ method ]
      **
-     * Adds a click event handler to the element.
+     * Adds a click event handler to the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -156,7 +156,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.unclick
      [ method ]
      **
-     * Removes a click event handler from the element.
+     * Removes a click event handler from the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -165,7 +165,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.dblclick
      [ method ]
      **
-     * Adds a double click event handler to the element.
+     * Adds a double click event handler to the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -173,7 +173,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.undblclick
      [ method ]
      **
-     * Removes a double click event handler from the element.
+     * Removes a double click event handler from the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -182,7 +182,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.mousedown
      [ method ]
      **
-     * Adds a mousedown event handler to the element.
+     * Adds a mousedown event handler to the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -190,7 +190,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.unmousedown
      [ method ]
      **
-     * Removes a mousedown event handler from the element.
+     * Removes a mousedown event handler from the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -199,7 +199,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.mousemove
      [ method ]
      **
-     * Adds a mousemove event handler to the element.
+     * Adds a mousemove event handler to the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -207,7 +207,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.unmousemove
      [ method ]
      **
-     * Removes a mousemove event handler from the element.
+     * Removes a mousemove event handler from the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -216,7 +216,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.mouseout
      [ method ]
      **
-     * Adds a mouseout event handler to the element.
+     * Adds a mouseout event handler to the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -224,7 +224,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.unmouseout
      [ method ]
      **
-     * Removes a mouseout event handler from the element.
+     * Removes a mouseout event handler from the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -233,7 +233,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.mouseover
      [ method ]
      **
-     * Adds a mouseover event handler to the element.
+     * Adds a mouseover event handler to the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -241,7 +241,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.unmouseover
      [ method ]
      **
-     * Removes a mouseover event handler from the element.
+     * Removes a mouseover event handler from the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -250,7 +250,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.mouseup
      [ method ]
      **
-     * Adds a mouseup event handler to the element.
+     * Adds a mouseup event handler to the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -258,7 +258,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.unmouseup
      [ method ]
      **
-     * Removes a mouseup event handler from the element.
+     * Removes a mouseup event handler from the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -267,7 +267,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.touchstart
      [ method ]
      **
-     * Adds a touchstart event handler to the element.
+     * Adds a touchstart event handler to the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -275,7 +275,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.untouchstart
      [ method ]
      **
-     * Removes a touchstart event handler from the element.
+     * Removes a touchstart event handler from the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -284,7 +284,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.touchmove
      [ method ]
      **
-     * Adds a touchmove event handler to the element.
+     * Adds a touchmove event handler to the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -292,7 +292,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.untouchmove
      [ method ]
      **
-     * Removes a touchmove event handler from the element.
+     * Removes a touchmove event handler from the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -301,7 +301,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.touchend
      [ method ]
      **
-     * Adds a touchend event handler to the element.
+     * Adds a touchend event handler to the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -309,7 +309,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.untouchend
      [ method ]
      **
-     * Removes a touchend event handler from the element.
+     * Removes a touchend event handler from the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -318,7 +318,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.touchcancel
      [ method ]
      **
-     * Adds a touchcancel event handler to the element.
+     * Adds a touchcancel event handler to the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -326,7 +326,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.untouchcancel
      [ method ]
      **
-     * Removes a touchcancel event handler from the element.
+     * Removes a touchcancel event handler from the element
      - handler (function) handler for the event
      = (object) @Element
     \*/
@@ -362,7 +362,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.hover
      [ method ]
      **
-     * Adds event handlers for hover for the element.
+     * Adds hover event handlers to the element
      - f_in (function) handler for hover in
      - f_out (function) handler for hover out
      - icontext (object) #optional context for hover in handler
@@ -376,7 +376,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.unhover
      [ method ]
      **
-     * Removes event handlers for hover for the element.
+     * Removes hover event handlers from the element
      - f_in (function) handler for hover in
      - f_out (function) handler for hover out
      = (object) @Element
@@ -393,7 +393,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.drag
      [ method ]
      **
-     * Adds event handlers for an element's drag gesture.
+     * Adds event handlers for an element's drag gesture
      **
      - onmove (function) handler for moving
      - onstart (function) handler for drag start
@@ -453,7 +453,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.onDragOver
      [ method ]
      **
-     * Shortcut for assigning event handler for `drag.over.<id>` event, where id is id of the element (see @Element.id).
+     * Shortcut to assign event handler for `drag.over.<id>` event, where `id` is the element's `id` (see @Element.id)
      - f (function) handler for event, first argument would be the element you are dragging over
     \*/
     // elproto.onDragOver = function (f) {
@@ -463,7 +463,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.undrag
      [ method ]
      **
-     * Removes all drag event handlers from given element.
+     * Removes all drag event handlers from the given element
     \*/
     elproto.undrag = function () {
         var i = draggable.length;
diff --git a/src/path.js b/src/path.js
index 3538fdd..bd159c5 100644
--- a/src/path.js
+++ b/src/path.js
@@ -1046,7 +1046,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Snap.path.getTotalLength
      [ method ]
      **
-     * Returns length of the given path in pixels.
+     * Returns the length of the given path in pixels
      **
      - path (string) SVG path string.
      **
@@ -1057,7 +1057,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Snap.path.getPointAtLength
      [ method ]
      **
-     * Return coordinates of the point located at the given length on the given path.
+     * Returns the coordinates of the point located at the given length along the given path
      **
      - path (string) SVG path string
      - length (number) length, in pixels, from the start of the path, excluding non-rendering jumps VERIFY
@@ -1074,7 +1074,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Snap.path.getSubpath
      [ method ]
      **
-     * Return subpath of a given path between given start and end lengths
+     * Returns the subpath of a given path between given start and end lengths
      **
      - path (string) SVG path string
      - from (number) length, in pixels, from the start of the path to the start of the segment VERIFY
@@ -1093,7 +1093,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.getTotalLength
      [ method ]
      **
-     * Returns length of the path in pixels. Only works for `path` elements.
+     * Returns the length of the path in pixels (only works for `path` elements)
      = (number) length.
     \*/
     elproto.getTotalLength = function () {
@@ -1106,7 +1106,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.getPointAtLength
      [ method ]
      **
-     * Return coordinates of the point located at the given length on the given path. Only works for `path` elements.
+     * Returns coordinates of the point located at the given length on the given path (only works for `path` elements)
      **
      - length (number) length, in pixels, from the start of the path, excluding non-rendering jumps VERIFY
      **
@@ -1125,7 +1125,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Element.getSubpath
      [ method ]
      **
-     * Return subpath of a given element from given start and end lengths. Only works for `path` elements.
+     * Returns  subpath of a given element from given start and end lengths (only works for `path` elements)
      **
      - from (number) length, in pixels, from the start of the path to the start of the segment VERIFY
      - to (number) length, in pixels, from the start of the path to the end of the segment VERIFY
@@ -1142,7 +1142,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      **
      * Utility method
      **
-     * Find dot coordinates on the given cubic beziér curve at the given t.
+     * Finds dot coordinates on the given cubic beziér curve at the given t
      - p1x (number) x of the first point of the curve
      - p1y (number) y of the first point of the curve
      - c1x (number) x of the first anchor of the curve
@@ -1182,7 +1182,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      **
      * Utility method
      **
-     * Return bounding box of a given cubic beziér curve
+     * Returns the bounding box of a given cubic beziér curve
      - p1x (number) x of the first point of the curve
      - p1y (number) y of the first point of the curve
      - c1x (number) x of the first anchor of the curve
@@ -1212,7 +1212,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      **
      * Utility method
      **
-     * Returns `true` if given point is inside bounding box.
+     * Returns `true` if given point is inside bounding box
      - bbox (string) bounding box
      - x (string) x coordinate of the point
      - y (string) y coordinate of the point
@@ -1263,7 +1263,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      **
      * Utility method
      **
-     * Returns `true` if given point is inside a given closed path.
+     * Returns `true` if given point is inside a given closed path
      - path (string) path string
      - x (number) x of the point
      - y (number) y of the point
@@ -1276,7 +1276,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      **
      * Utility method
      **
-     * Return bounding box of a given path
+     * Returns the bounding box of a given path
      - path (string) path string
      = (object) bounding box
      o {
@@ -1296,7 +1296,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      **
      * Utility method
      **
-     * Converts path coordinates into relative values.
+     * Converts path coordinates into relative values
      - path (string) path string
      = (array) path string
     \*/
@@ -1307,7 +1307,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      **
      * Utility method
      **
-     * Converts path coordinates into absolute values.
+     * Converts path coordinates into absolute values
      - path (string) path string
      = (array) path string
     \*/
@@ -1318,7 +1318,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      **
      * Utility method
      **
-     * Converts path to a new path where all segments are cubic beziér curves.
+     * Converts path to a new path where all segments are cubic beziér curves
      - pathString (string|array) path string or array of segments
      = (array) array of segments.
     \*/
@@ -1327,7 +1327,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Snap.path.map
      [ method ]
      **
-     * Transform the path string with given matrix.
+     * Transform the path string with the given matrix
      - path (string) path string
      - matrix (object) see @Matrix
      = (string) transformed path string
diff --git a/src/set.js b/src/set.js
index 9a51aa3..f95eb70 100644
--- a/src/set.js
+++ b/src/set.js
@@ -34,7 +34,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Set.push
      [ method ]
      **
-     * Adds each argument to the current set.
+     * Adds each argument to the current set
      = (object) original element
     \*/
     setproto.push = function () {
@@ -54,7 +54,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Set.pop
      [ method ]
      **
-     * Removes last element and returns it.
+     * Removes last element and returns it
      = (object) element
     \*/
     setproto.pop = function () {
@@ -65,7 +65,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Set.forEach
      [ method ]
      **
-     * Executes given function for each element in the set.
+     * Executes given function for each element in the set
      *
      * If the function returns `false`, the loop stops running.
      **
@@ -102,7 +102,7 @@ Snap.plugin(function (Snap, Element, Paper, glob) {
      * Set.splice
      [ method ]
      **
-     * Removes given element from the set
+     * Removes range of elements from the set
      **
      - index (number) position of the deletion
      - count (number) number of element to remove
diff --git a/src/svg.js b/src/svg.js
index 29215fe..ea6c1c2 100644
--- a/src/svg.js
+++ b/src/svg.js
@@ -19,7 +19,7 @@ Snap.version = "0.0.1";
  * Snap
  [ method ]
  **
- * Creates drawing surface or wraps existing SVG element.
+ * Creates a drawing surface or wraps existing SVG element
  **
  - width (number|string) width of surface
  - height (number|string) height of surface
@@ -154,7 +154,7 @@ function is(o, type) {
  * Snap.format
  [ method ]
  **
- * Replaces construction of type `{<name>}` to the corresponding argument.
+ * Replaces construction of type `{<name>}` to the corresponding argument
  **
  - token (string) string to format
  - json (object) object which properties are used as a replacement
@@ -294,7 +294,7 @@ Snap.deg = deg;
  * Snap.angle
  [ method ]
  **
- * Returns angle between two or three points.
+ * Returns an angle between two or three points
  > Parameters
  - x1 (number) x coord of first point
  - y1 (number) y coord of first point
@@ -309,7 +309,7 @@ Snap.angle = angle;
  * Snap.is
  [ method ]
  **
- * Handy replacement for the `typeof` operator.
+ * Handy replacement for the `typeof` operator
  - o (…) any object or primitive
  - type (string) name of the type, e.g., `string`, `function`, `number`, etc.
  = (boolean) if given value is of given type
@@ -319,7 +319,7 @@ Snap.is = is;
  * Snap.snapTo
  [ method ]
  **
- * Snaps given value to given grid.
+ * Snaps given value to given grid
  - values (array|number) given array of values or step of the grid
  - value (number) value to adjust
  - tolerance (number) #optional maximum distance to the target value that would trigger the snap. Default is `10`. VERIFY
@@ -377,7 +377,7 @@ function Matrix(a, b, c, d, e, f) {
      * Matrix.add
      [ method ]
      **
-     * Adds given matrix to existing one.
+     * Adds the given matrix to existing one
      - a (number)
      - b (number)
      - c (number)
@@ -419,7 +419,7 @@ function Matrix(a, b, c, d, e, f) {
      * Matrix.invert
      [ method ]
      **
-     * Returns inverted version of the matrix
+     * Returns an inverted version of the matrix
      = (object) @Matrix
     \*/
     matrixproto.invert = function () {
@@ -431,7 +431,7 @@ function Matrix(a, b, c, d, e, f) {
      * Matrix.clone
      [ method ]
      **
-     * Returns copy of the matrix
+     * Returns a copy of the matrix
      = (object) @Matrix
     \*/
     matrixproto.clone = function () {
@@ -488,7 +488,7 @@ function Matrix(a, b, c, d, e, f) {
      * Matrix.x
      [ method ]
      **
-     * Return x coordinate for given point after transformation described by the matrix. See also @Matrix.y
+     * Returns  x coordinate for given point after transformation described by the matrix. See also @Matrix.y
      - x (number)
      - y (number)
      = (number) x
@@ -500,7 +500,7 @@ function Matrix(a, b, c, d, e, f) {
      * Matrix.y
      [ method ]
      **
-     * Return y coordinate for given point after transformation described by the matrix. See also @Matrix.x
+     * Returns  y coordinate for given point after transformation described by the matrix. See also @Matrix.x
      - x (number)
      - y (number)
      = (number) y
@@ -582,7 +582,7 @@ function Matrix(a, b, c, d, e, f) {
      * Matrix.toTransformString
      [ method ]
      **
-     * Return transform string that represents given matrix
+     * Returns  transform string that represents given matrix
      = (string) transform string
     \*/
     matrixproto.toTransformString = function (shorter) {
@@ -606,7 +606,7 @@ function Matrix(a, b, c, d, e, f) {
  **
  * Utility method
  **
- * Returns matrix based on given parameters.
+ * Returns a matrix based on the given parameters
  - a (number)
  - b (number)
  - c (number)
@@ -735,7 +735,7 @@ Snap.getRGB = cacher(function (colour) {
  * Snap.hsb
  [ method ]
  **
- * Converts HSB values to hex representation of the colour.
+ * Converts HSB values to a hex representation of the colour
  - h (number) hue
  - s (number) saturation
  - b (number) value or brightness
@@ -748,7 +748,7 @@ Snap.hsb = cacher(function (h, s, b) {
  * Snap.hsl
  [ method ]
  **
- * Converts HSL values to hex representation of the colour.
+ * Converts HSL values to a hex representation of the colour
  - h (number) hue
  - s (number) saturation
  - l (number) luminosity
@@ -761,7 +761,7 @@ Snap.hsl = cacher(function (h, s, l) {
  * Snap.rgb
  [ method ]
  **
- * Converts RGB values to hex representation of the colour.
+ * Converts RGB values to a hex representation of the colour
  - r (number) red
  - g (number) green
  - b (number) blue
@@ -839,7 +839,7 @@ packageRGB = function (r, g, b, o) {
  * Snap.color
  [ method ]
  **
- * Parses the color string and returns an object featuring the color's component values.
+ * Parses the color string and returns an object featuring the color's component values
  - clr (string) color string in one of the supported formats. See @Snap.getRGB.
  = (object) Combined RGB & HSB object in the following format:
  o {
@@ -894,7 +894,7 @@ Snap.color = function (clr) {
  * Snap.hsb2rgb
  [ method ]
  **
- * Converts HSB values to RGB object.
+ * Converts HSB values to an RGB object
  - h (number) hue
  - s (number) saturation
  - v (number) value or brightness
@@ -930,7 +930,7 @@ Snap.hsb2rgb = function (h, s, v, o) {
  * Snap.hsl2rgb
  [ method ]
  **
- * Converts HSL values to RGB object.
+ * Converts HSL values to an RGB object
  - h (number) hue
  - s (number) saturation
  - l (number) luminosity
@@ -970,7 +970,7 @@ Snap.hsl2rgb = function (h, s, l, o) {
  * Snap.rgb2hsb
  [ method ]
  **
- * Converts RGB values to HSB object.
+ * Converts RGB values to an HSB object
  - r (number) red
  - g (number) green
  - b (number) blue
@@ -1003,7 +1003,7 @@ Snap.rgb2hsb = function (r, g, b) {
  * Snap.rgb2hsl
  [ method ]
  **
- * Converts RGB values to HSL object.
+ * Converts RGB values to an HSL object
  - r (number) red
  - g (number) green
  - b (number) blue
@@ -1044,7 +1044,7 @@ Snap.rgb2hsl = function (r, g, b) {
  **
  * Utility method
  **
- * Parses given path string into an array of arrays of path segments.
+ * Parses given path string into an array of arrays of path segments
  - pathString (string|array) path string or array of segments (in the last case it is returned straight away)
  = (array) array of segments.
 \*/
@@ -1098,7 +1098,7 @@ Snap.parsePathString = function (pathString) {
  **
  * Utility method
  **
- * Parses given transform string into an array of transformations.
+ * Parses given transform string into an array of transformations
  - TString (string|array) transform string or array of transformations (in the last case it is returned straight away)
  = (array) array of transformations.
 \*/
@@ -1364,7 +1364,7 @@ function unit2px(el, name, value) {
  * Snap.select
  [ method ]
  **
- * Wraps DOM element specified by CSS selector as @Element
+ * Wraps a DOM element specified by CSS selector as @Element
  - query (string) CSS selector of the element
  = (Element)
 \*/
@@ -1503,7 +1503,7 @@ function arrayFirstValue(arr) {
      * Element.getBBox
      [ method ]
      **
-     * Returns bounding box descriptor for the given element.
+     * Returns the bounding box descriptor for the given element
      **
      = (object) bounding box descriptor:
      o {
@@ -1617,7 +1617,7 @@ function arrayFirstValue(arr) {
      * Element.parent
      [ method ]
      **
-     * Returns parent of the element
+     * Returns the element's parent
      **
      = (Element) parent
     \*/
@@ -1628,7 +1628,7 @@ function arrayFirstValue(arr) {
      * Element.append
      [ method ]
      **
-     * Appends given element to current one.
+     * Appends the given element to current one
      **
      - el (Element|Set) element to append
      = (Element) parent
@@ -1637,7 +1637,7 @@ function arrayFirstValue(arr) {
      * Element.add
      [ method ]
      **
-     * See @Element.append.
+     * See @Element.append
     \*/
     elproto.append = elproto.add = function (el) {
         if (el.type == "set") {
@@ -1656,7 +1656,7 @@ function arrayFirstValue(arr) {
      * Element.prepend
      [ method ]
      **
-     * Prepends given element to current one.
+     * Prepends the given element to the current one
      **
      - el (Element) element to prepend
      = (Element) parent
@@ -1671,7 +1671,7 @@ function arrayFirstValue(arr) {
      * Element.before
      [ method ]
      **
-     * Inserts given element before the current one.
+     * Inserts given element before the current one
      **
      - el (Element) element to insert
      = (Element) parent
@@ -1687,7 +1687,7 @@ function arrayFirstValue(arr) {
      * Element.after
      [ method ]
      **
-     * Inserts given element after the current one.
+     * Inserts given element after the current one
      **
      - el (Element) element to insert
      = (Element) parent
@@ -1702,7 +1702,7 @@ function arrayFirstValue(arr) {
      * Element.insertBefore
      [ method ]
      **
-     * Inserts the element after the given one.
+     * Inserts the element after the given one
      **
      - el (Element) element next to whom insert to
      = (Element) parent
@@ -1717,7 +1717,7 @@ function arrayFirstValue(arr) {
      * Element.insertAfter
      [ method ]
      **
-     * Inserts the element after the given one.
+     * Inserts the element after the given one
      **
      - el (Element) element next to whom insert to
      = (Element) parent
@@ -1745,7 +1745,7 @@ function arrayFirstValue(arr) {
      * Element.select
      [ method ]
      **
-     * Gathers nested @Element matching the given set of CSS selectors.
+     * Gathers the nested @Element matching the given set of CSS selectors
      **
      - query (string) CSS selector
      = (Element) result of query selection
@@ -1757,7 +1757,7 @@ function arrayFirstValue(arr) {
      * Element.selectAll
      [ method ]
      **
-     * Gathers nested @Element objects matching the given set of CSS selectors.
+     * Gathers nested @Element objects matching the given set of CSS selectors
      **
      - query (string) CSS selector
      = (Set|array) result of query selection
@@ -1774,7 +1774,7 @@ function arrayFirstValue(arr) {
      * Element.asPX
      [ method ]
      **
-     * Return given attribute of the element as a `px` value. (Not %, em, etc.)
+     * Returns  given attribute of the element as a `px` value (not %, em, etc.)
      **
      - attr (string) attribute name
      - value (string) #optional attribute value
@@ -1791,7 +1791,7 @@ function arrayFirstValue(arr) {
      * Element.use
      [ method ]
      **
-     * Creates `<use>` element linked to the current element.
+     * Creates a `<use>` element linked to the current element
      **
      = (Element) `<use>` element
     \*/
@@ -1820,7 +1820,7 @@ function arrayFirstValue(arr) {
      * Element.clone
      [ method ]
      **
-     * Creates clone of the element and inserts it after the element.
+     * Creates a clone of the element and inserts it after the element
      **
      = (Element) the clone
     \*/
@@ -1900,7 +1900,7 @@ function arrayFirstValue(arr) {
      * Element.toDefs
      [ method ]
      **
-     * Moves element to the shared `<defs>` area.
+     * Moves element to the shared `<defs>` area
      **
      = (Element) the clone
     \*/
@@ -1915,7 +1915,7 @@ function arrayFirstValue(arr) {
      * Element.pattern
      [ method ]
      **
-     * Creates `<pattern>` element from the current element.
+     * Creates a `<pattern>` element from the current element
      **
      * To create a pattern you have to specify the pattern rect:
      - x (string|number)
@@ -1963,7 +1963,7 @@ function arrayFirstValue(arr) {
      * Element.marker
      [ method ]
      **
-     * Creates `<marker>` element from the current element.
+     * Creates a `<marker>` element from the current element
      **
      * To create a marker you have to specify the bounding rect and reference point:
      - x (number)
@@ -2026,7 +2026,7 @@ function arrayFirstValue(arr) {
      * Snap.animation
      [ method ]
      **
-     * Creates animation object.
+     * Creates an animation object
      **
      - attr (object) attributes of final destination
      - duration (number) duration of the animation, in milliseconds
@@ -2078,7 +2078,7 @@ function arrayFirstValue(arr) {
      * Snap.animate
      [ method ]
      **
-     * Runs generic animation of one number into another with a caring function.
+     * Runs generic animation of one number into another with a caring function
      **
      - from (number|array) number or array of numbers
      - to (number|array) number or array of numbers
@@ -2111,7 +2111,7 @@ function arrayFirstValue(arr) {
      * Element.stop
      [ method ]
      **
-     * Stops all the animations of the current element.
+     * Stops all the animations for the current element
      **
      = (Element) the element
     \*/
@@ -2128,7 +2128,7 @@ function arrayFirstValue(arr) {
      * Element.animate
      [ method ]
      **
-     * Animate given attributes of the element.
+     * Animates the given attributes of the element
      **
      - attrs (object) key-value pairs of destination attributes
      - duration (number) duration of the animation in milliseconds
@@ -2190,7 +2190,7 @@ function arrayFirstValue(arr) {
      * Element.data
      [ method ]
      **
-     * Adds or retrieves given value associated with given key.
+     * Adds or retrieves given value associated with given key
      ** 
      * See also @Element.removeData
      - key (string) key to store data
@@ -2246,7 +2246,7 @@ function arrayFirstValue(arr) {
      * Element.toString
      [ method ]
      **
-     * Returns SVG code of the element. Equivalent to `outerHTML` in HTML context.
+     * Returns SVG code of the element, equivalent to HTML's `outerHTML`
      = (string) SVG code of the element.
     \*/
     elproto.toString = toString(1);
@@ -2254,7 +2254,7 @@ function arrayFirstValue(arr) {
      * Element.innerSVG
      [ method ]
      **
-     * Returns SVG code of the element. Equivalent to `innerHTML` in HTML context.
+     * Returns SVG code of the element's contents, equivalent to HTML's `innerHTML`
      = (string) SVG code of the element.
     \*/
     elproto.innerSVG = toString();
@@ -2291,7 +2291,7 @@ function arrayFirstValue(arr) {
  * Snap.parse
  [ method ]
  **
- * Parses SVG fragment and converts it into @Fragment.
+ * Parses SVG fragment and converts it into @Fragment
  **
  - svg (string) SVG string
  = (Fragment) the fragment
@@ -2534,7 +2534,7 @@ function gradientRadial(defs, cx, cy, r, fx, fy) {
      * Paper.el
      [ method ]
      **
-     * Creates element on paper with a given name and no attributes.
+     * Creates an element on paper with a given name and no attributes
      **
      - name (string) tag name
      - attr (object) attributes
@@ -2554,7 +2554,7 @@ function gradientRadial(defs, cx, cy, r, fx, fy) {
      * Paper.rect
      [ method ]
      *
-     * Draws a rectangle.
+     * Draws a rectangle
      **
      - x (number) x coordinate of the top left corner
      - y (number) y coordinate of the top left corner
@@ -2597,7 +2597,7 @@ function gradientRadial(defs, cx, cy, r, fx, fy) {
      * Paper.circle
      [ method ]
      **
-     * Draws a circle.
+     * Draws a circle
      **
      - x (number) x coordinate of the centre
      - y (number) y coordinate of the centre
@@ -2625,7 +2625,7 @@ function gradientRadial(defs, cx, cy, r, fx, fy) {
      * Paper.image
      [ method ]
      **
-     * Embeds an image into the surface.
+     * Places an image on the surface
      **
      - src (string) URI of the source image
      - x (number) x offset position
@@ -2671,7 +2671,7 @@ function gradientRadial(defs, cx, cy, r, fx, fy) {
      * Paper.ellipse
      [ method ]
      **
-     * Draws an ellipse.
+     * Draws an ellipse
      **
      - x (number) x coordinate of the centre
      - y (number) y coordinate of the centre
@@ -2701,7 +2701,7 @@ function gradientRadial(defs, cx, cy, r, fx, fy) {
      * Paper.path
      [ method ]
      **
-     * Creates a path element using the given string as the path's definition.
+     * Creates a `<path>` element using the given string as the path's definition
      - pathString (string) #optional path string in SVG format.
      * Path string consists of one-letter commands, followed by comma seprarated arguments in numerical form. Example:
      | "M10,20L30,40"
@@ -2743,7 +2743,7 @@ function gradientRadial(defs, cx, cy, r, fx, fy) {
      * Paper.g
      [ method ]
      **
-     * Makes a group element.
+     * Creates a group element
      **
      - varargs (…) #optional elements to nest within the group
      = (object) `g` element
@@ -2781,7 +2781,7 @@ function gradientRadial(defs, cx, cy, r, fx, fy) {
      * Paper.text
      [ method ]
      **
-     * Draws a text string.
+     * Draws a text string
      **
      - x (number) x coordinate position
      - y (number) y coordinate position
@@ -2809,7 +2809,7 @@ function gradientRadial(defs, cx, cy, r, fx, fy) {
      * Paper.line
      [ method ]
      **
-     * Draws a line.
+     * Draws a line
      **
      - x1 (number) x coordinate position of the start
      - y1 (number) y coordinate position of the start
@@ -2838,7 +2838,7 @@ function gradientRadial(defs, cx, cy, r, fx, fy) {
      * Paper.polyline
      [ method ]
      **
-     * Draws a polyline.
+     * Draws a polyline
      **
      - points (array) array of points
      * or
@@ -2889,7 +2889,7 @@ function gradientRadial(defs, cx, cy, r, fx, fy) {
          * Paper.gradient
          [ method ]
          **
-         * Creates a gradient element.
+         * Creates a gradient element
          **
          - gradient (string) gradient descriptor
          > Gradient Descriptor
@@ -2935,8 +2935,8 @@ function gradientRadial(defs, cx, cy, r, fx, fy) {
          * Paper.toString
          [ method ]
          **
-         * Returns SVG code of the @Paper.
-         = (string) SVG code of the @Paper.
+         * Returns SVG code for the @Paper
+         = (string) SVG code for the @Paper.
         \*/
         proto.toString = function () {
             var f = glob.doc.createDocumentFragment(),
@@ -2958,7 +2958,7 @@ function gradientRadial(defs, cx, cy, r, fx, fy) {
  * Snap.ajax
  [ method ]
  **
- * Simple implementation of Ajax.
+ * Simple implementation of Ajax
  **
  - url (string) URL
  - postData (object|string) data for post request
@@ -3010,7 +3010,7 @@ Snap.ajax = function (url, postData, callback, scope){
  * Snap.load
  [ method ]
  **
- * Loads external SVG file as a @Fragment. For more advanced AJAX see @Snap.ajax.
+ * Loads external SVG file as a @Fragment (see @Snap.ajax for more advanced AJAX)
  **
  - url (string) URL
  - callback (function) callback