Write documentation for Project#addLayer() and #insertLayer()

Closes #903

src/basic/Rectangle.js

@@ -799,10 +799,10 @@ var Rectangle = Base.extend(/** @lends Rectangle# */{
         ['Right', 'Center'], ['Bottom', 'Center']
     ],
     function(parts, index) {
-        var part = parts.join('');
+        var part = parts.join(''),
-        // find out if the first of the pair is an x or y property,
+            // find out if the first of the pair is an x or y property,
-        // by checking the first character for [R]ight or [L]eft;
+            // by checking the first character for [R]ight or [L]eft;
-        var xFirst = /^[RL]/.test(part);
+            xFirst = /^[RL]/.test(part);
         // Rename Center to CenterX or CenterY:
         if (index >= 4)
             parts[1] += xFirst ? 'Y' : 'X';
@@ -861,8 +861,8 @@ new function() {
     var proto = Rectangle.prototype;
 
     return Base.each(['x', 'y', 'width', 'height'], function(key) {
-        var part = Base.capitalize(key);
+        var part = Base.capitalize(key),
-        var internal = '_' + key;
+            internal = '_' + key;
         this['get' + part] = function() {
             return this[internal];
         };

src/item/Item.js

@@ -2114,8 +2114,8 @@ var Item = Base.extend(Emitter, /** @lends Item# */{
      * {@grouptitle Hierarchy Operations}
      *
      * Adds the specified item as a child of this item at the end of the its
-     * children list. You can use this function for groups, compound paths and
+     * {@link #children}  list. You can use this function for groups, compound
-     * layers.
+     * paths and layers.
      *
      * @param {Item} item the item to be added as a child
      * @return {Item} the added item, or `null` if adding was not possible
@@ -2129,7 +2129,7 @@ var Item = Base.extend(Emitter, /** @lends Item# */{
      * in its {@link #children} list. You can use this function for groups,
      * compound paths and layers.
      *
-     * @param {Number} index
+     * @param {Number} index the index at which to insert the item
      * @param {Item} item the item to be inserted as a child
      * @return {Item} the inserted item, or `null` if inserting was not possible
      */

src/project/Project.js

@@ -269,44 +269,6 @@ var Project = PaperScopeItem.extend(/** @lends Project# */{
     },
     // TODO: Implement setSelectedItems?
 
-    insertLayer: function(index, item) {
-        if (item instanceof Layer) {
-            item._remove(false, true);
-            Base.splice(this._children, [item], index, 0);
-            item._setProject(this, true);
-            // See Item#_remove() for an explanation of this:
-            if (this._changes)
-                item._changed(/*#=*/Change.INSERTION);
-            // TODO: this._changed(/*#=*/Change.LAYERS);
-            // Also activate this layer if there was none before
-            if (!this._activeLayer)
-                this._activeLayer = item;
-        } else {
-            item = null;
-        }
-        return item;
-    },
-
-    addLayer: function(item) {
-        return this.insertLayer(undefined, item);
-    },
-
-    // Project#_insertItem() and Item#_insertItem() are helper functions called
-    // in Item#copyTo(), and through _getOwner() in the various Item#insert*()
-    // methods. They are called the same to facilitate so duck-typing.
-    _insertItem: function(index, item, _preserve, _created) {
-        item = this.insertLayer(index, item)
-                // Anything else than layers needs to be added to a layer first.
-                // If none exists yet, create one now, then add the item to it.
-                || (this._activeLayer || this._insertItem(undefined,
-                        new Layer(Item.NO_INSERT), true, true))
-                        .insertChild(index, item, _preserve);
-        // If a layer was newly created, also activate it.
-        if (_created && item.activate)
-            item.activate();
-        return item;
-    },
-
     _updateSelection: function(item) {
         var id = item._id,
             selectedItems = this._selectedItems;
@@ -390,6 +352,61 @@ var Project = PaperScopeItem.extend(/** @lends Project# */{
         return null;
     },
 
+    /**
+     * {@grouptitle Hierarchy Operations}
+     *
+     * Adds the specified layer at the end of the this project's {@link #layers}
+     * list.
+     *
+     * @param {Layer} layer the layer to be added to the project
+     * @return {Layer} the added layer, or `null` if adding was not possible
+     */
+    addLayer: function(layer) {
+        return this.insertLayer(undefined, layer);
+    },
+
+    /**
+     * Inserts the specified layer at the specified index in this project's
+     * {@link #layers} list.
+     *
+     * @param {Number} index the index at which to insert the layer
+     * @param {Item} item the item to be inserted in the project
+     * @return {Layer} the added layer, or `null` if adding was not possible
+     */
+    insertLayer: function(index, layer) {
+        if (layer instanceof Layer) {
+            layer._remove(false, true);
+            Base.splice(this._children, [layer], index, 0);
+            layer._setProject(this, true);
+            // See Item#_remove() for an explanation of this:
+            if (this._changes)
+                layer._changed(/*#=*/Change.INSERTION);
+            // TODO: this._changed(/*#=*/Change.LAYERS);
+            // Also activate this layer if there was none before
+            if (!this._activeLayer)
+                this._activeLayer = layer;
+        } else {
+            layer = null;
+        }
+        return layer;
+    },
+
+    // Project#_insertItem() and Item#_insertItem() are helper functions called
+    // in Item#copyTo(), and through _getOwner() in the various Item#insert*()
+    // methods. They are called the same to facilitate so duck-typing.
+    _insertItem: function(index, item, _preserve, _created) {
+        item = this.insertLayer(index, item)
+                // Anything else than layers needs to be added to a layer first.
+                // If none exists yet, create one now, then add the item to it.
+                || (this._activeLayer || this._insertItem(undefined,
+                        new Layer(Item.NO_INSERT), true, true))
+                        .insertChild(index, item, _preserve);
+        // If a layer was newly created, also activate it.
+        if (_created && item.activate)
+            item.activate();
+        return item;
+    },
+
     /**
      * {@grouptitle Fetching and matching items}
      *