From e63edba0b51207a4f04575261456cb118e0744b1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=BCrg=20Lehni?= <juerg@scratchdisk.com>
Date: Thu, 27 Jun 2013 18:03:03 -0700
Subject: [PATCH] Clean up various documentations a bit.

---
 src/basic/Rectangle.js        |  1 -
 src/basic/Size.js             | 10 ++++++----
 src/path/Path.Constructors.js | 22 +++++++++++-----------
 3 files changed, 17 insertions(+), 16 deletions(-)

diff --git a/src/basic/Rectangle.js b/src/basic/Rectangle.js
index 9a03acb2..de86b5f1 100644
--- a/src/basic/Rectangle.js
+++ b/src/basic/Rectangle.js
@@ -175,7 +175,6 @@ var Rectangle = Base.extend(/** @lends Rectangle# */{
 	 * @type Number
 	 */
 
-	// DOCS: Why does jsdocs document this function, when there are no comments?
 	/**
 	 * @ignore
 	 */
diff --git a/src/basic/Size.js b/src/basic/Size.js
index 4793e1c5..2aae6a0e 100644
--- a/src/basic/Size.js
+++ b/src/basic/Size.js
@@ -13,21 +13,23 @@
 /**
  * @name Size
  *
- * @class The Size object is used to describe the size of something, through
- * its {@link #width} and {@link #height} properties.
+ * @class The Size object is used to describe the size or dimensions of
+ * somethign, through its {@link #width} and {@link #height} properties.
  *
  * @classexample
- * // Create a size that is 10pt wide and 5pt high
+ * // Create a size that is 10pt wide and 5pt high,
+ * // and use it to define a rectangle:
  * var size = new Size(10, 5);
  * console.log(size.width); // 10
  * console.log(size.height); // 5
+ * var rect = new Rectangle(new Point(20, 15), size);
+ * console.log(rect); // { x: 20, y: 15, width: 10, height: 5 }
  */
 var Size = Base.extend(/** @lends Size# */{
 	_class: 'Size',
 	// Tell Base.read that the Point constructor supports reading with index
 	_readIndex: true,
 
-	// DOCS: improve Size class description
 	/**
 	 * Creates a Size object with the given width and height values.
 	 *
diff --git a/src/path/Path.Constructors.js b/src/path/Path.Constructors.js
index 9437fbfa..46e6e070 100644
--- a/src/path/Path.Constructors.js
+++ b/src/path/Path.Constructors.js
@@ -88,7 +88,7 @@ Path.inject({ statics: new function() {
 		/**
 		 * {@grouptitle Shaped Paths}
 		 *
-		 * Creates a Path Item with two anchor points forming a line.
+		 * Creates a Path item with two anchor points forming a line.
 		 *
 		 * @name Path.Line
 		 * @param {Point} from the first anchor point of the path
@@ -116,7 +116,7 @@ Path.inject({ statics: new function() {
 		},
 
 		/**
-		 * Creates a circle shaped Path Item.
+		 * Creates a circle shaped Path item.
 		 *
 		 * @param {Point} center the center point of the circle
 		 * @param {Number} radius the radius of the circle
@@ -142,7 +142,7 @@ Path.inject({ statics: new function() {
 		},
 
 		/**
-		 * Creates a rectangle shaped Path Item from the passed point and size.
+		 * Creates a rectangle shaped Path item from the passed point and size.
 		 *
 		 * @name Path.Rectangle
 		 * @param {Point} point
@@ -163,8 +163,8 @@ Path.inject({ statics: new function() {
 		 * });
 		 */
 		/**
-		 * Creates a rectangle shaped Path Item from the passed points. These do not
-		 * necessarily need to be the top left and bottom right corners, the
+		 * Creates a rectangle shaped Path item from the passed points. These do
+		 * not necessarily need to be the top left and bottom right corners, the
 		 * constructor figures out how to fit a rectangle between them.
 		 *
 		 * @name Path.Rectangle
@@ -186,7 +186,7 @@ Path.inject({ statics: new function() {
 		 * });
 		 */
 		/**
-		 * Creates a rectangle shaped Path Item from the passed abstract
+		 * Creates a rectangle shaped Path item from the passed abstract
 		 * {@link Rectangle}.
 		 *
 		 * @name Path.Rectangle
@@ -213,7 +213,7 @@ Path.inject({ statics: new function() {
 		 * });
 		 */
 		/**
-		 * Creates a rectangular Path Item with rounded corners.
+		 * Creates a rectangular Path item with rounded corners.
 		 *
 		 * @name Path.Rectangle
 		 * @param {Rectangle} rectangle
@@ -247,7 +247,7 @@ Path.inject({ statics: new function() {
 		RoundRectangle: createRectangle,
 
 		/**
-		 * Creates an ellipse shaped Path Item.
+		 * Creates an ellipse shaped Path item.
 		 *
 		 * @param {Rectangle} rectangle
 		 * @param {Boolean} [circumscribed=false] when set to {@code true} the
@@ -279,7 +279,7 @@ Path.inject({ statics: new function() {
 		Oval: createEllipse,
 
 		/**
-		 * Creates a circular arc shaped Path Item.
+		 * Creates a circular arc shaped Path item.
 		 *
 		 * @param {Point} from the starting point of the circular arc
 		 * @param {Point} through the point the arc passes through
@@ -312,7 +312,7 @@ Path.inject({ statics: new function() {
 		},
 
 		/**
-		 * Creates a regular polygon shaped Path Item.
+		 * Creates a regular polygon shaped Path item.
 		 *
 		 * @param {Point} center the center point of the polygon
 		 * @param {Number} sides the number of sides of the polygon
@@ -354,7 +354,7 @@ Path.inject({ statics: new function() {
 		},
 
 		/**
-		 * Creates a star shaped Path Item.
+		 * Creates a star shaped Path item.
 		 *
 		 * The largest of {@code radius1} and {@code radius2} will be the outer
 		 * radius of the star. The smallest of radius1 and radius2 will be the