From ca3230c1ad502106dc9c3a33b32b25958a7e1df0 Mon Sep 17 00:00:00 2001
From: Jonathan Puckey <me@jonathanpuckey.com>
Date: Fri, 27 May 2011 13:28:13 +0200
Subject: [PATCH] Documentation: reorder functions, add group titles and todos.

---
 src/basic/Point.js         |   8 +++
 src/basic/Rectangle.js     |  88 ++++++++++++++++++++++++++-----
 src/basic/Size.js          |  50 +++++++++++++-----
 src/item/Layer.js          |   7 +--
 src/item/PathStyle.js      |   4 +-
 src/item/Raster.js         | 104 +++++++++++++++++++------------------
 src/path/Path.js           |  28 +++++++++-
 src/path/Segment.js        |   8 +--
 src/project/Symbol.js      |  45 +++++++++-------
 src/text/ParagraphStyle.js |  16 +++---
 src/text/PointText.js      |  14 ++---
 src/tool/Tool.js           |   6 ++-
 12 files changed, 259 insertions(+), 119 deletions(-)

diff --git a/src/basic/Point.js b/src/basic/Point.js
index b391d842..a62c05f4 100644
--- a/src/basic/Point.js
+++ b/src/basic/Point.js
@@ -30,6 +30,14 @@ var Point = this.Point = Base.extend({
 	 * @class The Point object represents a point in the two dimensional space
 	 * of the Paper.js project. It is also used to represent two dimensional
 	 * vector objects.
+	 * 
+	 * Sample code:
+	 * <pre>
+	 * // Create a point at x: 10, y: 5
+	 * var point = new Point(10, 5);
+	 * console.log(point.x); // 10
+	 * console.log(point.y); // 5
+	 * </pre>
 	 */
 	initialize: function(arg0, arg1) {
 		if (arg1 !== undefined) {
diff --git a/src/basic/Rectangle.js b/src/basic/Rectangle.js
index 747027e7..fabaab43 100644
--- a/src/basic/Rectangle.js
+++ b/src/basic/Rectangle.js
@@ -115,7 +115,7 @@ var Rectangle = this.Rectangle = Base.extend({
 		return this;
 	},
 
-	/*
+	/**
 	 * The top-left point of the rectangle
 	 *
 	 * @type Point
@@ -132,7 +132,7 @@ var Rectangle = this.Rectangle = Base.extend({
 		return this;
 	},
 
-	/*
+	/**
 	 * The size of the rectangle
 	 *
 	 * @type Size
@@ -222,6 +222,7 @@ var Rectangle = this.Rectangle = Base.extend({
 	 * 
 	 * @type number
 	 * @bean
+	 * @ignore
 	 */
 	getCenterX: function() {
 		return this.x + this.width * 0.5;
@@ -237,6 +238,7 @@ var Rectangle = this.Rectangle = Base.extend({
 	 * 
 	 * @type number
 	 * @bean
+	 * @ignore
 	 */
 	getCenterY: function() {
 		return this.y + this.height * 0.5;
@@ -248,6 +250,8 @@ var Rectangle = this.Rectangle = Base.extend({
 	},
 
 	/**
+	 * {@grouptitle Corner and Center Point Positions}
+	 * 
 	 * The center point of the rectangle.
 	 * 
 	 * @type Point
@@ -265,6 +269,62 @@ var Rectangle = this.Rectangle = Base.extend({
 
 	// DOCS: Rectangle#topLeft, Rectangle#topRight etc.
 
+	/**
+	 * The top-left point of the rectangle.
+	 * 
+	 * @name Rectangle#topLeft
+	 * @type Point
+	 */
+
+	/**
+	 * The top-right point of the rectangle.
+	 * 
+	 * @name Rectangle#topRight
+	 * @type Point
+	 */
+
+	/**
+	 * The bottom-left point of the rectangle.
+	 * 
+	 * @name Rectangle#bottomLeft
+	 * @type Point
+	 */
+
+	/**
+	 * The bottom-right point of the rectangle.
+	 * 
+	 * @name Rectangle#bottomRight
+	 * @type Point
+	 */
+
+	/**
+	 * The left-center point of the rectangle.
+	 * 
+	 * @name Rectangle#leftCenter
+	 * @type Point
+	 */
+
+	/**
+	 * The top-center point of the rectangle.
+	 * 
+	 * @name Rectangle#topCenter
+	 * @type Point
+	 */
+
+	/**
+	 * The right-center point of the rectangle.
+	 * 
+	 * @name Rectangle#rightCenter
+	 * @type Point
+	 */
+
+	/**
+	 * The bottom-center point of the rectangle.
+	 * 
+	 * @name Rectangle#bottomCenter
+	 * @type Point
+	 */
+
 	// DOCS: Rectangle#equals
 	/**
 	 * @param {Rectangle} rect
@@ -283,6 +343,18 @@ var Rectangle = this.Rectangle = Base.extend({
 		return this.width == 0 || this.height == 0;
 	},
 
+	/**
+	 * @return {string} A string representation of this rectangle.
+	 */
+	toString: function() {
+		var format = Base.formatNumber;
+		return '{ x: ' + format(this.x)
+				+ ', y: ' + format(this.y)
+				+ ', width: ' + format(this.width)
+				+ ', height: ' + format(this.height)
+				+ ' }';
+	},
+
 	/**
 	 * {@grouptitle Geometric Tests}
 	 * 
@@ -391,18 +463,6 @@ var Rectangle = this.Rectangle = Base.extend({
 		return Rectangle.create(x1, y1, x2 - x1, y2 - y1);
 	},
 
-	/**
-	 * @return {string} A string representation of this rectangle.
-	 */
-	toString: function() {
-		var format = Base.formatNumber;
-		return '{ x: ' + format(this.x)
-				+ ', y: ' + format(this.y)
-				+ ', width: ' + format(this.width)
-				+ ', height: ' + format(this.height)
-				+ ' }';
-	},
-
 	statics: {
 		// See Point.create()
 		create: function(x, y, width, height) {
diff --git a/src/basic/Size.js b/src/basic/Size.js
index 34a92ef5..5ce1ea6d 100644
--- a/src/basic/Size.js
+++ b/src/basic/Size.js
@@ -27,6 +27,14 @@ var Size = this.Size = Base.extend({
 	 * @param {number} height the height
 	 * 
 	 * @class The Size object represents the size of something.
+	 * 
+	 * Sample code:
+	 * <pre>
+	 * // Create a size that is 10pt wide and 5pt height
+	 * var size = new Size(10, 5);
+	 * console.log(size.width); // 10
+	 * console.log(size.height); // 5
+	 * </pre>
 	 */
 	initialize: function(arg0, arg1) {
 		if (arg1 !== undefined) {
@@ -54,6 +62,15 @@ var Size = this.Size = Base.extend({
 		}
 	},
 
+	/**
+	 * @return {string} A string representation of the size.
+	 */
+	toString: function() {
+		var format = Base.formatNumber;
+		return '{ width: ' + format(this.width)
+				+ ', height: ' + format(this.height) + ' }';
+	},
+
 	/**
 	 * The width of the size
 	 *
@@ -254,9 +271,9 @@ var Size = this.Size = Base.extend({
 	 * 
 	 * @example
 	 * var size = new Size(5, 10);
-	 * print(size == new Size(5, 10)); // true
-	 * print(size == new Size(1, 1)); // false
-	 * print(size != new Size(1, 1)); // true
+	 * console.log(size == new Size(5, 10)); // true
+	 * console.log(size == new Size(1, 1)); // false
+	 * console.log(size != new Size(1, 1)); // true
 	 *
 	 * @param {Size}
 	 * @return {boolean}
@@ -267,6 +284,7 @@ var Size = this.Size = Base.extend({
 	},
 
 	/**
+	 * {@grouptitle Tests}
 	 * Checks if this size has both the width and height set to 0.
 	 * 
 	 * @return {boolean} true if both width and height are 0, false otherwise.
@@ -285,15 +303,6 @@ var Size = this.Size = Base.extend({
 		return isNaN(this.width) || isNaN(this.height);
 	},
 
-	/**
-	 * @return {string} A string representation of the size.
-	 */
-	toString: function() {
-		var format = Base.formatNumber;
-		return '{ width: ' + format(this.width)
-				+ ', height: ' + format(this.height) + ' }';
-	},
-
 	statics: {
 		/** @lends Size */
 
@@ -306,6 +315,12 @@ var Size = this.Size = Base.extend({
 		 * Returns a new size object with the smallest {@link #width} and
 		 * {@link #height} of the supplied sizes.
 		 * 
+		 * @example
+		 * var size1 = new Size(10, 100);
+		 * var size2 = new Size(200, 5);
+		 * var minSize = Size.min(size1, size2);
+		 * console.log(minSize); // { width: 10.0, height: 5.0 }
+		 * 
 		 * @static
 		 * @param {Size} size1
 		 * @param {Size} size2
@@ -321,6 +336,12 @@ var Size = this.Size = Base.extend({
 		 * Returns a new size object with the largest {@link #width} and
 		 * {@link #height} of the supplied sizes.
 		 * 
+		 * @example
+		 * var size1 = new Size(10, 100);
+		 * var size2 = new Size(200, 5);
+		 * var maxSize = Size.max(size1, size2);
+		 * console.log(maxSize); // { width: 200.0, height: 100.0 }
+		 * 
 		 * @static
 		 * @param {Size} size1
 		 * @param {Size} size2
@@ -336,6 +357,11 @@ var Size = this.Size = Base.extend({
 		 * Returns a size object with random {@link #width} and {@link #height}
 		 * values between {@code 0} and {@code 1}.
 		 * 
+		 * @example
+		 * var maxSize = new Size(100, 100);
+		 * var randomSize = Size.random();
+		 * var size = maxSize * randomSize;
+		 * 
 		 * @returns {Size} The newly created size object
 		 * @static
 		 */
diff --git a/src/item/Layer.js b/src/item/Layer.js
index 2850e8e8..bd27ea6c 100644
--- a/src/item/Layer.js
+++ b/src/item/Layer.js
@@ -22,7 +22,8 @@ var Layer = this.Layer = Group.extend({
 	// DOCS: improve constructor code example.
 	/**
 	 * Creates a new Layer item and places it at the end of the
-	 * {@link Project#layers} array.
+	 * {@link Project#layers} array. The newly created layer will be activated,
+	 * so all newly created items will be placed within it.
 	 * 
 	 * @example
 	 * var layer = new Layer();
@@ -69,14 +70,14 @@ var Layer = this.Layer = Group.extend({
 				: this._project.layers[this._index - 1] || null;
 	},
 
+	// DOCS: improve Layer#activate() example.
 	/**
 	 * Activates the layer.
 	 * 
 	 * @example
 	 * var layer = new Layer();
-	 * layer.name = 'new layer';
 	 * layer.activate();
-	 * console.log(project.activeLayer.name) // 'new layer'
+	 * console.log(project.activeLayer == layer); // true
 	 */
 	activate: function() {
 		this._project.activeLayer = this;
diff --git a/src/item/PathStyle.js b/src/item/PathStyle.js
index a887adb5..f6deda37 100644
--- a/src/item/PathStyle.js
+++ b/src/item/PathStyle.js
@@ -54,7 +54,8 @@ var PathStyle = this.PathStyle = Base.extend(new function() {
 		 * {@link Item#style}. This is a convenient way to define a style once and
 		 * apply it to a series of items:
 		 * 
-		 * @example
+		 * Sample Code:
+		 * <pre>
 		 * var circleStyle = {
 		 * 	fillColor: new RGBColor(1, 0, 0),
 		 * 	strokeColor: new GrayColor(1),
@@ -63,6 +64,7 @@ var PathStyle = this.PathStyle = Base.extend(new function() {
 		 * 
 		 * var path = new Path.Circle(new Point(50, 50), 50);
 		 * path.style = circleStyle;
+		 * </pre>
 		 */
 		initialize: function(style) {
 			// Note: This relies on bean setters that get implicetly
diff --git a/src/item/Raster.js b/src/item/Raster.js
index 143486ad..dd18038c 100644
--- a/src/item/Raster.js
+++ b/src/item/Raster.js
@@ -202,57 +202,6 @@ var Raster = this.Raster = Item.extend({
 		this.getContext().drawImage(image, point.x, point.y);
 	},
 
-	/**
-	 * Gets the color of a pixel in the raster.
-	 *
-	 * @name Raster#getPixel^2
-	 * @function
-	 * @param x the x offset of the pixel in pixel coordinates
-	 * @param y the y offset of the pixel in pixel coordinates
-	 * @return {RGBColor} the color of the pixel
-	 */
-	/**
-	 * Gets the color of a pixel in the raster.
-	 * @param point the offset of the pixel as a point in pixel coordinates
-	 * @return {RGBColor} the color of the pixel
-	 */
-	getPixel: function(point) {
-		point = Point.read(arguments);
-		var pixels = this.getContext().getImageData(point.x, point.y, 1, 1).data,
-			channels = new Array(4);
-		for (var i = 0; i < 4; i++)
-			channels[i] = pixels[i] / 255;
-		return RGBColor.read(channels);
-	},
-
-	/**
-	 * Sets the color of the specified pixel to the specified color.
-	 *
-	 * @name Raster#setPixel^2
-	 * @function
-	 * @param x the x offset of the pixel in pixel coordinates
-	 * @param y the y offset of the pixel in pixel coordinates
-	 * @param color the color that the pixel will be set to
-	 */
-	/**
-	 * Sets the color of the specified pixel to the specified color.
-	 * @param point the offset of the pixel as a point in pixel coordinates
-	 * @param color the color that the pixel will be set to
-	 */
-	setPixel: function(point, color) {
-		var hasPoint = arguments.length == 2;
-		point = Point.read(arguments, 0, hasPoint ? 1 : 2);
-		color = Color.read(arguments, hasPoint ? 1 : 2);
-		var ctx = this.getContext(),
-			imageData = ctx.createImageData(1, 1),
-			alpha = color.getAlpha();
-		imageData.data[0] = color.getRed() * 255;
-		imageData.data[1] = color.getGreen() * 255;
-		imageData.data[2] = color.getBlue() * 255;
-		imageData.data[3] = alpha != null ? alpha * 255 : 255;
-		ctx.putImageData(imageData, point.x, point.y);
-	},
-
 	/**
 	 * Calculates the average color of the image within the given path,
 	 * rectangle or point. This can be used for creating raster image
@@ -325,8 +274,61 @@ var Raster = this.Raster = Item.extend({
 		return total ? Color.read(channels) : null;
 	},
 
+	/**
+	 * {@grouptitle Pixels}
+	 * Gets the color of a pixel in the raster.
+	 *
+	 * @name Raster#getPixel^2
+	 * @function
+	 * @param x the x offset of the pixel in pixel coordinates
+	 * @param y the y offset of the pixel in pixel coordinates
+	 * @return {RGBColor} the color of the pixel
+	 */
+	/**
+	 * Gets the color of a pixel in the raster.
+	 * @param point the offset of the pixel as a point in pixel coordinates
+	 * @return {RGBColor} the color of the pixel
+	 */
+	getPixel: function(point) {
+		point = Point.read(arguments);
+		var pixels = this.getContext().getImageData(point.x, point.y, 1, 1).data,
+			channels = new Array(4);
+		for (var i = 0; i < 4; i++)
+			channels[i] = pixels[i] / 255;
+		return RGBColor.read(channels);
+	},
+
+	/**
+	 * Sets the color of the specified pixel to the specified color.
+	 *
+	 * @name Raster#setPixel^2
+	 * @function
+	 * @param x the x offset of the pixel in pixel coordinates
+	 * @param y the y offset of the pixel in pixel coordinates
+	 * @param color the color that the pixel will be set to
+	 */
+	/**
+	 * Sets the color of the specified pixel to the specified color.
+	 * @param point the offset of the pixel as a point in pixel coordinates
+	 * @param color the color that the pixel will be set to
+	 */
+	setPixel: function(point, color) {
+		var hasPoint = arguments.length == 2;
+		point = Point.read(arguments, 0, hasPoint ? 1 : 2);
+		color = Color.read(arguments, hasPoint ? 1 : 2);
+		var ctx = this.getContext(),
+			imageData = ctx.createImageData(1, 1),
+			alpha = color.getAlpha();
+		imageData.data[0] = color.getRed() * 255;
+		imageData.data[1] = color.getGreen() * 255;
+		imageData.data[2] = color.getBlue() * 255;
+		imageData.data[3] = alpha != null ? alpha * 255 : 255;
+		ctx.putImageData(imageData, point.x, point.y);
+	},
+
 	// DOCS: document Raster#createData
 	/**
+	 * {@grouptitle Image Data}
 	 * @param {Size} size
 	 * @return {ImageData}
 	 */
diff --git a/src/path/Path.js b/src/path/Path.js
index 32b683cb..0f52853e 100644
--- a/src/path/Path.js
+++ b/src/path/Path.js
@@ -929,6 +929,8 @@ var Path = this.Path = PathItem.extend({
 
 		// DOCS: document moveTo
 		/**
+		 * {@grouptitle Postscript Style Drawing Commands}
+		 * 
 		 * @param {Point} point
 		 */
 		moveTo: function(point) {
@@ -990,7 +992,7 @@ var Path = this.Path = PathItem.extend({
 			);
 		},
 
-		// DOCS: document curveTo
+		// DOCS: document Path#curveTo
 		/**
 		 * @param {Point} through
 		 * @param {Point} to
@@ -1012,6 +1014,11 @@ var Path = this.Path = PathItem.extend({
 			this.quadraticCurveTo(handle, to);
 		},
 
+		// DOCS: document Path#arcTo
+		/**
+		 * @param {Point} to
+		 * @param {boolean} [clockwise=true]
+		 */
 		arcTo: function(to, clockwise) {
 			// Get the start point:
 			var current = getCurrentSegment(this),
@@ -1095,12 +1102,22 @@ var Path = this.Path = PathItem.extend({
 			this._add(segments);
 		},
 
+		// DOCS: document Path#lineBy
+		/**
+		 * @param {Point} vector
+		 */
 		lineBy: function(vector) {
 			vector = Point.read(arguments);
 			var current = getCurrentSegment(this);
 			this.lineTo(current._point.add(vector));
 		},
 
+		// DOCS: document Path#curveBy
+		/**
+		 * @param {Point} throughVector
+		 * @param {Point} toVector
+		 * @param {number} [parameter=0.5]
+		 */
 		curveBy: function(throughVector, toVector, parameter) {
 			throughVector = Point.read(throughVector);
 			toVector = Point.read(toVector);
@@ -1109,6 +1126,11 @@ var Path = this.Path = PathItem.extend({
 					parameter);
 		},
 
+		// DOCS: document Path#arcBy
+		/**
+		 * @param {Point} throughVector
+		 * @param {Point} toVector
+		 */
 		arcBy: function(throughVector, toVector) {
 			throughVector = Point.read(throughVector);
 			toVector = Point.read(toVector);
@@ -1116,6 +1138,10 @@ var Path = this.Path = PathItem.extend({
 			this.arcBy(current.add(throughVector), current.add(toVector));
 		},
 
+		/**
+		 * Closes the path. When closed, Paper.js connects the first and last
+		 * segments.
+		 */
 		closePath: function() {
 			this.setClosed(true);
 		}
diff --git a/src/path/Segment.js b/src/path/Segment.js
index 94d5361f..e3817657 100644
--- a/src/path/Segment.js
+++ b/src/path/Segment.js
@@ -45,7 +45,7 @@ var Segment = this.Segment = Base.extend({
 	 * @constructor
 	 * 
 	 * @class The Segment object represents a part of a path which is
-	 * described by the {@link Path##segments} array. Every segment of a
+	 * described by the {@link Path#segments} array. Every segment of a
 	 * path corresponds to an anchor point (anchor points are the path handles
 	 * that are visible when the path is selected).
 	 */
@@ -214,7 +214,8 @@ var Segment = this.Segment = Base.extend({
 	 * {@grouptitle Sibling Segments}
 	 * 
 	 * The next segment in the {@link Path#segments} array that the segment
-	 * belongs to.
+	 * belongs to. If the segments belongs to a closed path, the first segment
+	 * is returned for the last segment of the path.
 	 *
 	 * @type Segment
 	 * @bean
@@ -227,7 +228,8 @@ var Segment = this.Segment = Base.extend({
 
 	/**
 	 * The previous segment in the {@link Path#segments} array that the
-	 * segment belongs to.
+	 * segment belongs to. If the segments belongs to a closed path, the last
+	 * segment is returned for the first segment of the path.
 	 *
 	 * @type Segment
 	 * @bean
diff --git a/src/project/Symbol.js b/src/project/Symbol.js
index 889d44b4..bbf7c9ab 100644
--- a/src/project/Symbol.js
+++ b/src/project/Symbol.js
@@ -22,25 +22,6 @@ var Symbol = this.Symbol = Base.extend({
 	/**
 	 * Creates a Symbol item.
 	 * 
-	 * Sample code:
-	 * @example
-	 * var circlePath = new Path.Circle(new Point(100, 100), 50);
-	 * circlePath.fillColor = 'red';
-	 * 
-	 * var circleSymbol = new Symbol(circlePath);
-	 * circleSymbol.name = 'Circle';
-	 * 
-	 * // The original item is still contained in the document:
-	 * circlePath.remove();
-	 * 
-	 * // The symbol can now also be accessed
-	 * // through project.symbols:
-	 * console.log(project.symbols['Circle']);
-	 * 
-	 * // To place instances of the symbol in the document:
-	 * var placedCircle = new PlacedSymbol(circleSymbol);
-	 * placedCircle.position = new Point(150, 150);
-	 * 
 	 * @param {Item} item the source item which is copied as the definition of
 	 *               the symbol
 	 *
@@ -53,6 +34,21 @@ var Symbol = this.Symbol = Base.extend({
 	 *        around complex objects, since internal properties such as segment
 	 *        lists and gradient positions don't need to be updated with every
 	 *        transformation.
+	 * 
+	 * Sample code:
+	 * <pre>
+	 * var circlePath = new Path.Circle(new Point(100, 100), 50);
+	 * circlePath.fillColor = 'red';
+	 * 
+	 * var circleSymbol = new Symbol(circlePath);
+	 * 
+	 * // The original item is still contained in the document:
+	 * circlePath.remove();
+	 * 
+	 * // To place instances of the symbol in the document:
+	 * var placedCircle = new PlacedSymbol(circleSymbol);
+	 * placedCircle.position = new Point(150, 150);
+	 * </pre>
 	 */
 	initialize: function(item) {
 		this.project = paper.project;
@@ -60,7 +56,16 @@ var Symbol = this.Symbol = Base.extend({
 		this.setDefinition(item);
 	},
 
-	// TODO: remove()
+	// TODO: Symbol#remove()
+	// TODO: Size#name (accessible by name through project#symbols)
+
+	/**
+	 * The project that this symbol belongs to.
+	 * 
+	 * @type Project
+	 * @readonly
+	 * @name Symbol#project
+	 */
 
 	/**
 	 * The symbol definition.
diff --git a/src/text/ParagraphStyle.js b/src/text/ParagraphStyle.js
index c598a9c4..44465d41 100644
--- a/src/text/ParagraphStyle.js
+++ b/src/text/ParagraphStyle.js
@@ -21,10 +21,6 @@ var ParagraphStyle = this.ParagraphStyle = Base.extend({
 	 * ParagraphStyle objects don't need to be created directly. Just pass an
 	 * object to {@link TextItem#paragraphStyle}, it will be converted to a
 	 * ParagraphStyle object internally.
-	 * 
-	 * Currently, the ParagraphStyle object may seem a bit empty, with just the
-	 * {@link #justification} property. Yet, we have lots in store for Paper.js
-	 * when it comes to typography. Please stay tuned.
 	 *
 	 * @constructs ParagraphStyle
 	 * @param {object} style
@@ -32,13 +28,19 @@ var ParagraphStyle = this.ParagraphStyle = Base.extend({
 	 * @constructs ParagraphStyle
 	 *
 	 * @class The ParagraphStyle object represents the paragraph style of a text
-	 * item ({@link TextItem#paragraphStyle})
+	 * item ({@link TextItem#paragraphStyle}).
 	 * 
-	 * @example
+	 * Currently, the ParagraphStyle object may seem a bit empty, with just the
+	 * {@link #justification} property. Yet, we have lots in store for Paper.js
+	 * when it comes to typography. Please stay tuned.
+	 * 
+	 * Sample code:
+	 * <pre>
 	 * var text = new PointText(new Point(0,0));
 	 * text.fillColor = 'black';
 	 * text.content = 'Hello world.';
 	 * text.paragraphStyle.justification = 'center';
+	 * </pre>
 	 */
 	initialize: function(style) {
 		Base.initialize(this, style, {
@@ -51,7 +53,7 @@ var ParagraphStyle = this.ParagraphStyle = Base.extend({
 	 *
 	 * @name ParagraphStyle#justification
 	 * @default 'left'
-	 * @type string
+	 * @type String('left', 'right', 'center')
 	 */
 
 	statics: {
diff --git a/src/text/PointText.js b/src/text/PointText.js
index 79d21bd2..c2d7e63b 100644
--- a/src/text/PointText.js
+++ b/src/text/PointText.js
@@ -22,12 +22,6 @@ var PointText = this.PointText = TextItem.extend({
 	/**
 	 * Creates a point text item
 	 * 
-	 * @example
-	 * var text = new PointText(new Point(50, 100));
-	 * text.paragraphStyle.justification = 'center';
-	 * text.content = 'The contents of the point text';
-	 * text.fillColor = 'black';
-	 * 
 	 * @param {Point} point the position where the text will start
 	 * 
 	 * @constructs PointText
@@ -36,6 +30,14 @@ var PointText = this.PointText = TextItem.extend({
 	 * project which starts from a certain point and extends by the amount of
 	 * characters contained in it.
 	 * 
+	 * Sample code:
+	 * <pre>
+	 * var text = new PointText(new Point(50, 100));
+	 * text.paragraphStyle.justification = 'center';
+	 * text.content = 'The contents of the point text';
+	 * text.fillColor = 'black';
+	 * </pre>
+	 * 
 	 * @extends TextItem
 	 * @extends Item
 	 */
diff --git a/src/tool/Tool.js b/src/tool/Tool.js
index 163b0f4a..2a53ba64 100644
--- a/src/tool/Tool.js
+++ b/src/tool/Tool.js
@@ -35,7 +35,8 @@ var Tool = this.Tool = Base.extend({
 	 * {@link #onMouseDrag}, {@link #onMouseUp}) or a keyboard handler
 	 * function ({@link #onKeyDown}, {@link #onKeyUp}).
 	 * 
-	 * @example
+	 * Example code:
+	 * <pre>
 	 * var path;
 	 * 
 	 * // Only execute onMouseDrag when the mouse
@@ -52,6 +53,7 @@ var Tool = this.Tool = Base.extend({
 	 * 	// Add a point to the path every time the mouse is dragged
 	 * 	path.lineTo(event.point);
 	 * }
+	 * </pre>
 	 */
 	initialize: function(handlers, scope) {
 		this._scope = scope;
@@ -194,6 +196,8 @@ var Tool = this.Tool = Base.extend({
 
 	// DOCS: document Tool#onKeyDown
 	/**
+	 * {@grouptitle Keyboard Event Handlers}
+	 * 
 	 * @name Tool#onKeyDown
 	 * @property
 	 * @type function