From 3416d8a090b65d604cf62e5d9d080ff2e6fa5269 Mon Sep 17 00:00:00 2001
From: kangax <kangax@gmail.com>
Date: Thu, 13 Dec 2012 15:36:43 +0100
Subject: [PATCH] Documentation additions.

---
 src/circle.class.js        |  8 +++++---
 src/ellipse.class.js       |  4 +++-
 src/freedrawing.class.js   | 14 ++++++++------
 src/gradient.class.js      |  5 +++++
 src/group.class.js         | 10 ++++++----
 src/image.class.js         | 35 +++++++++++++++++++++--------------
 src/line.class.js          |  8 +++++---
 src/parser.js              |  2 +-
 src/path.class.js          |  2 +-
 src/polygon.class.js       |  9 +++++----
 src/polyline.class.js      |  3 ++-
 src/static_canvas.class.js |  2 +-
 src/text.class.js          |  2 +-
 src/triangle.class.js      |  8 +++++---
 src/util/misc.js           |  4 ++--
 15 files changed, 71 insertions(+), 45 deletions(-)

diff --git a/src/circle.class.js b/src/circle.class.js
index 1290105b..c1d7e359 100644
--- a/src/circle.class.js
+++ b/src/circle.class.js
@@ -12,12 +12,14 @@
   }
 
   /**
+   * Circle class
    * @class Circle
    * @extends fabric.Object
    */
   fabric.Circle = fabric.util.createClass(fabric.Object, /** @scope fabric.Circle.prototype */ {
 
     /**
+     * Type of an object
      * @property
      * @type String
      */
@@ -133,10 +135,10 @@
    * Returns {@link fabric.Circle} instance from an SVG element
    * @static
    * @method fabric.Circle.fromElement
-   * @param element {SVGElement} element to parse
-   * @param options {Object} options object
+   * @param {SVGElement} element Element to parse
+   * @param {Object} [options] Options object
    * @throws {Error} If value of `r` attribute is missing or invalid
-   * @return {Object} instance of fabric.Circle
+   * @return {Object} Instance of fabric.Circle
    */
   fabric.Circle.fromElement = function(element, options) {
     options || (options = { });
diff --git a/src/ellipse.class.js b/src/ellipse.class.js
index 1037410f..11cc8a8c 100644
--- a/src/ellipse.class.js
+++ b/src/ellipse.class.js
@@ -12,12 +12,14 @@
   }
 
   /**
+   * Ellipse class
    * @class Ellipse
    * @extends fabric.Object
    */
   fabric.Ellipse = fabric.util.createClass(fabric.Object, /** @scope fabric.Ellipse.prototype */ {
 
     /**
+     * Type of an object
      * @property
      * @type String
      */
@@ -27,7 +29,7 @@
      * Constructor
      * @method initialize
      * @param {Object} [options] Options object
-     * @return {Object} thisArg
+     * @return {fabric.Ellipse} thisArg
      */
     initialize: function(options) {
       options = options || { };
diff --git a/src/freedrawing.class.js b/src/freedrawing.class.js
index a638727b..a9aae2fa 100644
--- a/src/freedrawing.class.js
+++ b/src/freedrawing.class.js
@@ -19,9 +19,9 @@
      * It converts the hand writting to a SVG Path and adds this
      * path to the canvas.
      *
-     * @metod init
-     * @param fabricCanvas {FabricCanvas}
-     *
+     * @metod initialize
+     * @param fabricCanvas {fabric.Canvas}
+     * @return {fabric.FreeDrawing}
      */
     initialize: function(fabricCanvas) {
       this.canvas = fabricCanvas;
@@ -127,9 +127,11 @@
      },
 
      /**
-     * @method getPathBoundingBox
-     * @param points {Array of points}
-     */
+      * Retursn bounding box of a path based on given points
+      * @method getPathBoundingBox
+      * @param points {Array}
+      * @return {Object}
+      */
      getPathBoundingBox: function(points) {
       var xBounds = [],
           yBounds = [],
diff --git a/src/gradient.class.js b/src/gradient.class.js
index e977f944..6bd803cc 100644
--- a/src/gradient.class.js
+++ b/src/gradient.class.js
@@ -30,6 +30,7 @@
   fabric.Gradient = fabric.util.createClass(/** @scope fabric.Gradient.prototype */ {
 
     /**
+     * Constructor
      * @method initialize
      * @param options optional Options with x1, y1, x2, y2 and colorStops
      */
@@ -80,6 +81,7 @@
   fabric.util.object.extend(fabric.Gradient, {
 
     /**
+     * Returns {@link fabric.Gradient} instance from an SVG element
      * @method fromElement
      * @static
      * @memberof fabric.Gradient
@@ -135,8 +137,11 @@
     },
 
     /**
+     * Returns {@link fabric.Gradient} instance from its object representation
      * @method forObject
      * @static
+     * @param obj
+     * @param [options]
      * @memberof fabric.Gradient
      */
     forObject: function(obj, options) {
diff --git a/src/group.class.js b/src/group.class.js
index 35023d89..338afe8e 100644
--- a/src/group.class.js
+++ b/src/group.class.js
@@ -23,12 +23,14 @@
   };
 
   /**
+   * Group class
    * @class Group
    * @extends fabric.Object
    */
   fabric.Group = fabric.util.createClass(fabric.Object, /** @scope fabric.Group.prototype */ {
 
     /**
+     * Type of an object
      * @property
      * @type String
      */
@@ -510,12 +512,12 @@
   });
 
   /**
-   * Returns fabric.Group instance from an object representation
+   * Returns {@link fabric.Group} instance from an object representation
    * @static
    * @method fabric.Group.fromObject
-   * @param object {Object} object to create a group from
-   * @param options {Object} options object
-   * @return {fabric.Group} an instance of fabric.Group
+   * @param {Object} object Object to create a group from
+   * @param {Object} [options] Options object
+   * @return {fabric.Group} An instance of fabric.Group
    */
   fabric.Group.fromObject = function(object, callback) {
     fabric.util.enlivenObjects(object.objects, function(enlivenedObjects) {
diff --git a/src/image.class.js b/src/image.class.js
index e626777e..d514ee0b 100644
--- a/src/image.class.js
+++ b/src/image.class.js
@@ -14,18 +14,14 @@
   }
 
   /**
+   * Image class
    * @class Image
    * @extends fabric.Object
    */
   fabric.Image = fabric.util.createClass(fabric.Object, /** @scope fabric.Image.prototype */ {
 
     /**
-     * @property
-     * @type Boolean
-     */
-    active: false,
-
-    /**
+     * Type of an object
      * @property
      * @type String
      */
@@ -34,7 +30,8 @@
     /**
      * Constructor
      * @param {HTMLImageElement | String} element Image element
-     * @param {Object} options optional
+     * @param {Object} [options] Options object
+     * @return {fabric.Image}
      */
     initialize: function(element, options) {
       options || (options = { });
@@ -127,9 +124,9 @@
     },
 
     /**
-     * Returns svg representation of an instance
+     * Returns SVG representation of an instance
      * @method toSVG
-     * @return {string} svg representation of an instance
+     * @return {String} svg representation of an instance
      */
     toSVG: function() {
       return '<g transform="' + this.getSvgTransform() + '">'+
@@ -164,7 +161,7 @@
 
     /**
      * Returns a clone of an instance
-     * @mthod clone
+     * @method clone
      * @param {Array} propertiesToInclude
      * @param {Function} callback Callback is invoked with a clone as a first argument
      */
@@ -268,7 +265,7 @@
     /**
      * @private
      * @method _initConfig
-     * @param {Object} options Options object
+     * @param {Object} [options] Options object
      */
     _initConfig: function(options) {
       options || (options = { });
@@ -292,7 +289,7 @@
     /**
      * @private
      * @method _setWidthHeight
-     * @param {Object} options Object with width/height properties
+     * @param {Object} [options] Object with width/height properties
      */
     _setWidthHeight: function(options) {
       this.width = 'width' in options
@@ -321,14 +318,19 @@
    */
   fabric.Image.CSS_CANVAS = "canvas-img";
 
+  /**
+   * Alias for getSrc
+   * @static
+   * @method getSvgSrc
+   */
   fabric.Image.prototype.getSvgSrc = fabric.Image.prototype.getSrc;
 
   /**
    * Creates an instance of fabric.Image from its object representation
    * @static
    * @method fromObject
-   * @param object {Object}
-   * @param callback {Function} optional
+   * @param {Object} object
+   * @param {Function} [callback] Callback to invoke when an image instance is created
    */
   fabric.Image.fromObject = function(object, callback) {
     var img = fabric.document.createElement('img'),
@@ -397,6 +399,11 @@
     fabric.Image.fromURL(parsedAttributes['xlink:href'], callback, extend(parsedAttributes, options));
   };
 
+  /**
+   * Indicates that instances of this type are async
+   * @static
+   * @type Boolean
+   */
   fabric.Image.async = true;
 
 })(typeof exports !== 'undefined' ? exports : this);
diff --git a/src/line.class.js b/src/line.class.js
index ea14f1ee..bc3b3d09 100644
--- a/src/line.class.js
+++ b/src/line.class.js
@@ -12,12 +12,14 @@
   }
 
   /**
+   * Line class
    * @class Line
    * @extends fabric.Object
    */
   fabric.Line = fabric.util.createClass(fabric.Object, /** @scope fabric.Line.prototype */ {
 
     /**
+     * Type of an object
      * @property
      * @type String
      */
@@ -50,7 +52,7 @@
     /**
      * @private
      * @method _setWidthHeight
-     * @param {Object} options
+     * @param {Object} [options] Options
      */
     _setWidthHeight: function(options) {
       options || (options = { });
@@ -128,9 +130,9 @@
     },
 
     /**
-     * Returns svg representation of an instance
+     * Returns SVG representation of an instance
      * @method toSVG
-     * @return {string} svg representation of an instance
+     * @return {String} svg representation of an instance
      */
     toSVG: function() {
       return [
diff --git a/src/parser.js b/src/parser.js
index 0948323a..1dc5c5ca 100644
--- a/src/parser.js
+++ b/src/parser.js
@@ -320,7 +320,7 @@
    * @method parseElements
    * @param {Array} elements Array of elements to parse
    * @param {Function} callback Being passed an array of fabric instances (transformed from SVG elements)
-   * @param {Object} options Options object
+   * @param {Object} [options] Options object
    * @param {Function} [reviver] Method for further parsing of SVG elements, called after each fabric object created.
    */
   function parseElements(elements, callback, options, reviver) {
diff --git a/src/path.class.js b/src/path.class.js
index 83d50fff..78f5144e 100644
--- a/src/path.class.js
+++ b/src/path.class.js
@@ -778,7 +778,7 @@
    * @static
    * @method fabric.Path.fromElement
    * @param {SVGElement} element to parse
-   * @param {Object} options object
+   * @param {Object} [options] Options object
    * @return {fabric.Path} Instance of fabric.Path
    */
   fabric.Path.fromElement = function(element, options) {
diff --git a/src/polygon.class.js b/src/polygon.class.js
index 2f888e88..1af1e67a 100644
--- a/src/polygon.class.js
+++ b/src/polygon.class.js
@@ -14,6 +14,7 @@
   }
 
   /**
+   * Polygon class
    * @class Polygon
    * @extends fabric.Object
    */
@@ -30,7 +31,7 @@
      * Constructor
      * @method initialize
      * @param {Array} points Array of points
-     * @param {Object} options Options object
+     * @param {Object} [options] Options object
      * @return {fabric.Polygon} thisArg
      */
     initialize: function(points, options) {
@@ -74,7 +75,7 @@
     /**
      * Returns svg representation of an instance
      * @method toSVG
-     * @return {string} svg representation of an instance
+     * @return {String} svg representation of an instance
      */
     toSVG: function() {
       var points = [];
@@ -131,11 +132,11 @@
   fabric.Polygon.ATTRIBUTE_NAMES = 'fill fill-opacity opacity stroke stroke-width transform'.split(' ');
 
   /**
-   * Returns fabric.Polygon instance from an SVG element
+   * Returns {@link fabric.Polygon} instance from an SVG element
    * @static
    * @method fabric.Polygon.fromElement
    * @param {SVGElement} element Element to parse
-   * @param {Object} options Options object
+   * @param {Object} [options] Options object
    * @return {fabric.Polygon}
    */
   fabric.Polygon.fromElement = function(element, options) {
diff --git a/src/polyline.class.js b/src/polyline.class.js
index 31d38a8c..23df7e1d 100644
--- a/src/polyline.class.js
+++ b/src/polyline.class.js
@@ -11,6 +11,7 @@
   }
 
   /**
+   * Polyline class
    * @class Polyline
    * @extends fabric.Object
    */
@@ -56,7 +57,7 @@
     },
 
     /**
-     * Returns svg representation of an instance
+     * Returns SVG representation of an instance
      * @method toSVG
      * @return {string} svg representation of an instance
      */
diff --git a/src/static_canvas.class.js b/src/static_canvas.class.js
index c3827e0f..1ae13857 100644
--- a/src/static_canvas.class.js
+++ b/src/static_canvas.class.js
@@ -244,7 +244,7 @@
 
     /**
      * @method _initOptions
-     * @param {Object} options
+     * @param {Object} [options]
      */
     _initOptions: function (options) {
       for (var prop in options) {
diff --git a/src/text.class.js b/src/text.class.js
index 5f854781..cbb2a7bf 100644
--- a/src/text.class.js
+++ b/src/text.class.js
@@ -577,7 +577,7 @@
     },
 
     /**
-     * Returns svg representation of an instance
+     * Returns SVG representation of an instance
      * @method toSVG
      * @return {string} svg representation of an instance
      */
diff --git a/src/triangle.class.js b/src/triangle.class.js
index 771a7601..d9545346 100644
--- a/src/triangle.class.js
+++ b/src/triangle.class.js
@@ -10,12 +10,14 @@
   }
 
   /**
+   * Triangle class
    * @class Triangle
    * @extends fabric.Object
    */
   fabric.Triangle = fabric.util.createClass(fabric.Object, /** @scope fabric.Triangle.prototype */ {
 
     /**
+     * Type of an object
      * @property
      * @type String
      */
@@ -24,7 +26,7 @@
     /**
      * Constructor
      * @method initialize
-     * @param options {Object} options object
+     * @param {Object} [options] Options object
      * @return {Object} thisArg
      */
     initialize: function(options) {
@@ -69,9 +71,9 @@
     },
 
     /**
-     * Returns svg representation of an instance
+     * Returns SVG representation of an instance
      * @method toSVG
-     * @return {string} svg representation of an instance
+     * @return {String} svg representation of an instance
      */
     toSVG: function() {
 
diff --git a/src/util/misc.js b/src/util/misc.js
index 11566edc..56ebcb87 100644
--- a/src/util/misc.js
+++ b/src/util/misc.js
@@ -211,8 +211,8 @@
    * @memberOf fabric.util
    * @method groupSVGElements
    * @param {Array} elements
-   * @param {Object} options optional
-   * @return {String} path optional
+   * @param {Object} [options] Options object
+   * @return {fabric.Object|fabric.PathGroup}
    */
   function groupSVGElements(elements, options, path) {
     var object = elements.length > 1