Clean up documentation for Project#getItems() / Item#getItems().

src/item/Item.js

@@ -1812,11 +1812,13 @@ var Item = Base.extend(Emitter, /** @lends Item# */{
      * Checks whether the item matches the criteria described by the given
      * object, by iterating over all of its properties and matching against
      * their values through {@link #matches(name, compare)}.
+     * See {@link Project#getItems(match)} for a selection of illustrated
+     * examples.
      *
-     * @name #matches
+     * @name Item#matches
      * @function
      *
-     * @see Project#getItems(match)
+     * @see #getItems(match)
      * @param {Object} match the criteria to match against.
      * @return {@true if the item matches all the criteria}
      */
@@ -1827,11 +1829,13 @@ var Item = Base.extend(Emitter, /** @lends Item# */{
      * 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}.
+     * See {@link Project#getItems(match)} for a selection of illustrated
+     * examples.
      *
-     * @name #matches
+     * @name Item#matches
      * @function
      *
-     * @see Project#getItems(match)
+     * @see #getItems(match)
      * @param {String} name the name of the state to match against.
      * @param {Object} compare the value, function or regular expression to
      * compare against.
@@ -1899,10 +1903,12 @@ var Item = Base.extend(Emitter, /** @lends Item# */{
      * 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}.
+     * See {@link Project#getItems(match)} for a selection of illustrated
+     * examples.
      *
-     * @see Project#getItems(match)
+     * @see #matches(match)
-     * @param {Object} match The criteria to match against.
+     * @param {Object} match the criteria to match against.
-     * @return {Item[]}
+     * @return {Item[]} the list of matching descendant items.
      */
     getItems: function(match) {
         return Item._getItems(this._children, match);
@@ -1916,10 +1922,12 @@ var Item = Base.extend(Emitter, /** @lends Item# */{
      * 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}.
+     * See {@link Project#getItems(match)} for a selection of illustrated
+     * examples.
      *
-     * @see Project#getItem(match)
+     * @see #getItems(match)
-     * @param {Object} match The criteria to match against.
+     * @param {Object} match the criteria to match against.
-     * @return {Item}
+     * @return {Item} the first descendant item  matching the given criteria.
      */
     getItem: function(match) {
         return Item._getItems(this._children, match, true)[0] || null;

src/project/Project.js

@@ -339,6 +339,8 @@ var Project = PaperScopeItem.extend(/** @lends Project# */{
     },
 
     /**
+     * {@grouptitle Fetching and matching items}
+     *
      * Fetch items contained within the project whose properties match the
      * criteria in the specified object.
      * Extended matching is possible by providing a compare function or
@@ -550,8 +552,10 @@ var Project = PaperScopeItem.extend(/** @lends Project# */{
      *  items[i].fillColor = 'red';
      * }
      *
-     * @param {Object} match The criteria to match against.
+     * @see Item#matches(match)
-     * @return {Item[]}
+     * @see Item#getItems(match)
+     * @param {Object} match the criteria to match against.
+     * @return {Item[]} the list of matching items contained in the project.
      */
     getItems: function(match) {
         return Item._getItems(this.layers, match);
@@ -565,205 +569,13 @@ var Project = PaperScopeItem.extend(/** @lends Project# */{
      * 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}.
+     * See {@link #getItems(match)} for a selection of illustrated examples.
      *
-     * @example {@paperscript} // Fetch all selected path items:
+     * @param {Object} match the criteria to match against.
-     * var path1 = new Path.Circle({
+     * @return {Item} the first item in the project matching the given criteria.
-     *     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, true)[0] || null;
+        return Item._getItems(this.layers, match, null, null, true)[0] || null;
     },
 
     /**