Add more matching docs.

src/project/Project.js

@@ -363,7 +363,7 @@ var Project = PaperScopeItem.extend(/** @lends Project# */{
 	 *     fillColor: 'purple'
 	 * });
 	 * 
-	 * // Change the fill color of the selected path to red:
+	 * // Select the fetched item:
 	 * items[0].selected = true;
 	 * 
 	 * @example {@paperscript} // Fetch items at a specific position:
@@ -524,12 +524,217 @@ var Project = PaperScopeItem.extend(/** @lends Project# */{
 	 * }
 	 * 
 	 * @param {Object} match The criteria to match against.
+	 * @return {Item[]}
 	 */
 	getItems: function(match) {
 		return Item._getItems(this.layers, match, true);
 	},
 
-	// DOCS: Project#getItems
+	/**
+	 * Fetch the first item contained within the project whose properties 
+	 * match the criteria in the specified object.
+	 * Extended matching is possible by providing a compare function or
+	 * regular expression. Matching points, colors only work as a comparison 
+	 * of the full object, not partial matching (e.g. only providing the x-
+	 * coordinate to match all points with that x-value). Partial matching 
+	 * does work for {@link Item#data}.
+	 *
+	 * @example {@paperscript} // Fetch all selected path items:
+	 * var path1 = new Path.Circle({
+	 *     center: [50, 50],
+	 *     radius: 25,
+	 *     fillColor: 'black'
+	 * });
+	 * 
+	 * var path2 = new Path.Circle({
+	 *     center: [150, 50],
+	 *     radius: 25,
+	 *     fillColor: 'black'
+	 * });
+	 * 
+	 * // Select path2:
+	 * path2.selected = true;
+	 * 
+	 * // Fetch first select path items:
+	 * var item = project.getItem({
+	 *     selected: true,
+	 *     class: Path
+	 * });
+	 * 
+	 * // Change the fill color of the selected path to red:
+	 * item.fillColor = 'red';
+	 *
+	 * @example {@paperscript} // Fetch item with a specific fill color:
+	 * var path1 = new Path.Circle({
+	 *     center: [50, 50],
+	 *     radius: 25,
+	 *     fillColor: 'black'
+	 * });
+	 * 
+	 * var path2 = new Path.Circle({
+	 *     center: [150, 50],
+	 *     radius: 25,
+	 *     fillColor: 'purple'
+	 * });
+	 * 
+	 * // Fetch first item with a purple fill color:
+	 * var item = project.getItem({
+	 *     fillColor: 'purple'
+	 * });
+	 * 
+	 * // Select the fetched item:
+	 * item.selected = true;
+	 * 
+	 * @example {@paperscript} // Fetch item at a specific position:
+	 * var path1 = new Path.Circle({
+	 *     center: [50, 50],
+	 *     radius: 25,
+	 *     fillColor: 'black'
+	 * });
+	 * 
+	 * var path2 = new Path.Circle({
+	 *     center: [150, 50],
+	 *     radius: 25,
+	 *     fillColor: 'black'
+	 * });
+	 * 
+	 * // Fetch path item positioned at {x: 150, y: 150}:
+	 * var item = project.getItem({
+	 *     position: [150, 50]
+	 * });
+	 * 
+	 * // Select the fetched path:
+	 * item.selected = true;
+	 * 
+	 * @example {@paperscript} // Fetch item using a comparing function:
+	 * 
+	 * // Create a circle shaped path:
+	 * var path1 = new Path.Circle({
+	 *     center: [50, 50],
+	 *     radius: 25,
+	 *     fillColor: 'black'
+	 * });
+	 * 
+	 * // Create a circle shaped path with 50% opacity:
+	 * var path2 = new Path.Circle({
+	 *     center: [150, 50],
+	 *     radius: 25,
+	 *     fillColor: 'black',
+	 *     opacity: 0.5
+	 * });
+	 * 
+	 * // Fetch first item whose opacity is smaller than 1
+	 * var item = paper.project.getItem({
+	 *     opacity: function(value) {
+	 *         return value < 1;
+	 *     }
+	 * });
+	 * 
+	 * // Select the fetched item:
+	 * item.selected = true;
+	 *
+	 * @example {@paperscript} // Fetch item using a comparing function (2):
+	 * 
+	 * // Create a rectangle shaped path (4 segments):
+	 * var path1 = new Path.Rectangle({
+	 *     from: [25, 25],
+	 *     to: [75, 75],
+	 *     strokeColor: 'black',
+	 *     strokeWidth: 10
+	 * });
+	 * 
+	 * // Create a line shaped path (2 segments):
+	 * var path2 = new Path.Line({
+	 *     from: [125, 50],
+	 *     to: [175, 50],
+	 *     strokeColor: 'black',
+	 *     strokeWidth: 10
+	 * });
+	 * 
+	 * // Fetch first path with 2 segments:
+	 * var item = project.getItem({
+	 *     class: Path,
+	 * 	segments: function(segments) {
+	 *         return segments.length == 2;
+	 * 	}
+	 * });
+	 * 
+	 * // Select the fetched path:
+	 * item.selected = true;
+	 * 
+	 * @example {@paperscript} // Match (nested) properties of the data property:
+	 * 
+	 * // Create a black circle shaped path:
+	 * var path1 = new Path.Circle({
+	 *     center: [50, 50],
+	 *     radius: 25,
+	 *     fillColor: 'black',
+	 *     data: {
+	 *         person: {
+	 *             name: 'john',
+	 *             length: 200,
+	 *             hair: true
+	 *         }
+	 *     }
+	 * });
+	 * 
+	 * // Create a red circle shaped path:
+	 * var path2 = new Path.Circle({
+	 *     center: [150, 50],
+	 *     radius: 25,
+	 *     fillColor: 'red',
+	 *     data: {
+	 *         person: {
+	 *             name: 'john',
+	 *             length: 180,
+	 *             hair: false
+	 *         }
+	 *     }
+	 * });
+	 * 
+	 * // Fetch item whose data object contains a person
+	 * // object whose name is john and length is 180:
+	 * var item = paper.project.getItem({
+	 *     data: {
+	 *         person: {
+	 *             name: 'john',
+	 *             length: 180
+	 *         }
+	 *     }
+	 * });
+	 * 
+	 * // Select the fetched item:
+	 * item.selected = true;
+	 * 
+	 * @example {@paperscript} // Match strings using regular expressions:
+	 * 
+	 * // Create a path named 'aardvark':
+	 * var path1 = new Path.Circle({
+	 *     center: [50, 50],
+	 *     radius: 25,
+	 *     fillColor: 'black',
+	 *     name: 'aardvark'
+	 * });
+	 * 
+	 * // Create a path named 'apple':
+	 * var path2 = new Path.Circle({
+	 *     center: [150, 50],
+	 *     radius: 25,
+	 *     fillColor: 'black',
+	 *     name: 'apple'
+	 * });
+	 * 
+	 * // Fetch the first item that has a name starting with 'a':
+	 * var item = project.getItem({
+	 *     name: /^a/
+	 * });
+	 * 
+	 * // Change the fill color of the matched item:
+	 * item.fillColor = 'red';
+	 * 
+	 * @param {Object} match The criteria to match against.
+	 * @return {Item}
+	 */
 	getItem: function(match) {
 		return Item._getItems(this.layers, match, false);
 	},