From ab09a44dc682bceca6edf46cf97d652a5f9b50a6 Mon Sep 17 00:00:00 2001
From: Jonathan Puckey <me@jonathanpuckey.com>
Date: Sun, 5 Jun 2011 16:11:13 +0200
Subject: [PATCH] Add examples to Path#join documentation.

---
 src/path/Path.js | 57 +++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 52 insertions(+), 5 deletions(-)

diff --git a/src/path/Path.js b/src/path/Path.js
index 312d1bfd..8d990c3c 100644
--- a/src/path/Path.js
+++ b/src/path/Path.js
@@ -544,11 +544,58 @@ var Path = this.Path = PathItem.extend({
 
 	// DOCS: document Path#join in more detail.
 	/**
-	* Joins the path with the specified path, which will be removed in the
-	* process.
-	* 
-	* @param {Path} path
-	*/
+	 * Joins the path with the specified path, which will be removed in the
+	 * process.
+	 * 
+	 * @param {Path} path
+	 * 
+	 * @example {@paperscript}
+	 * // Joining two paths:
+	 * var path = new Path([30, 25], [30, 75]);
+	 * path.strokeColor = 'black';
+	 * 
+	 * var path2 = new Path([200, 25], [200, 75]);
+	 * path2.strokeColor = 'black';
+	 * 
+	 * // Join the paths:
+	 * path.join(path2);
+	 * 
+	 * @example {@paperscript}
+	 * // Joining two paths that share a point at the start or end of their
+	 * // segments array:
+	 * var path = new Path([30, 25], [30, 75]);
+	 * path.strokeColor = 'black';
+	 * 
+	 * var path2 = new Path([30, 25], [80, 25]);
+	 * path2.strokeColor = 'black';
+	 * 
+	 * // Join the paths:
+	 * path.join(path2);
+	 * 
+	 * // After joining, path with have 3 segments, since it
+	 * // shared its first segment point with the first
+	 * // segment point of path2.
+	 * 
+	 * // Select the path to show that they have joined:
+	 * path.selected = true;
+	 * 
+	 * @example {@paperscript}
+	 * // Joining two paths that connect at two points:
+	 * var path = new Path([30, 25], [80, 25], [80, 75]);
+	 * path.strokeColor = 'black';
+	 * 
+	 * var path2 = new Path([30, 25], [30, 75], [80, 75]);
+	 * path2.strokeColor = 'black';
+	 * 
+	 * // Join the paths:
+	 * path.join(path2);
+	 * 
+	 * // Because the paths were joined at two points, the path is closed
+	 * // and has 4 segments.
+	 * 
+	 * // Select the path to show that they have joined:
+	 * path.selected = true;
+	 */
 	join: function(path) {
 		if (path) {
 			var segments = path._segments,