From b80393cb56b2fe5cb28e345bfa6a731827f3639d Mon Sep 17 00:00:00 2001
From: Dan Rasmussen <dra@debitoor.com>
Date: Tue, 17 Jan 2017 09:45:55 +0100
Subject: [PATCH] add-comments-to-functions

---
 README.md             |  2 +-
 index.js              | 20 ++++++++++++++++++++
 test/examples.spec.js | 22 +++++++++++++++++++++-
 3 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 278f3ce..93a59b8 100644
--- a/README.md
+++ b/README.md
@@ -163,7 +163,7 @@ dotProp.delete(obj, 'foo.0.bar');
 
 ### toggle
 
-Delete a value by a dot path.
+Toggle a boolean a value by a dot path.
 
 ```javascript
 var obj = {foo: { bar: true } };
diff --git a/index.js b/index.js
index 509cdba..ca70837 100644
--- a/index.js
+++ b/index.js
@@ -1,5 +1,11 @@
 'use strict';
 
+/**
+ * Set a value by a dot path.
+ * @param obj The object to evaluate.
+ * @param prop The path to be set.
+ * @param val The value to set.
+ */
 module.exports.set = function(obj, prop, value) {
 	prop = typeof prop === 'number' ? propToArray(prop.toString()) : typeof prop === 'string' ? propToArray(prop) : prop;
 
@@ -23,6 +29,11 @@ module.exports.set = function(obj, prop, value) {
 	return setPropImmutableRec(obj, prop, value, 0);
 };
 
+/**
+ * Get a value by a dot path.
+ * @param obj The object to evaluate.
+ * @param prop The path to value that should be returned.
+ */
 module.exports.get = function(obj, prop) {
 	prop = typeof prop === 'number' ? propToArray(prop.toString()) : typeof prop === 'string' ? propToArray(prop) : prop;
 
@@ -40,6 +51,14 @@ module.exports.get = function(obj, prop) {
 	return obj;
 };
 
+/**
+ * Delete a property by a dot path.
+ * If target container is an object, the property is deleted.
+ * If target container is an array, the index is deleted.
+ * If target container is undefined, nothing is deleted.
+ * @param obj The object to evaluate.
+ * @param prop The path to the property or index that should be deleted.
+ */
 module.exports.delete = function(obj, prop) {
 	prop = typeof prop === 'number' ? propToArray(prop.toString()) : typeof prop === 'string' ? propToArray(prop) : prop;
 
@@ -98,6 +117,7 @@ module.exports.toggle = function(obj, prop) {
  * If target is null or undefined, the value is simply set.
  * @param obj The object to evaluate.
  * @param prop The path to the value.
+ * @param val The value to merge into the target value.
  */
 module.exports.merge = function(obj, prop, val) {
 	var curVal = this.get(obj, prop);
diff --git a/test/examples.spec.js b/test/examples.spec.js
index a48a766..7942cbe 100644
--- a/test/examples.spec.js
+++ b/test/examples.spec.js
@@ -125,12 +125,32 @@ describe('examples.spec.js', function() {
 
 	describe('when delete', function() {
 
-		it('Array element', function() {
+		it('Array element by index', function() {
+			expect(dotProp.delete({foo: [{ bar: 'gold-unicorn'}, 'white-unicorn', 'silver-unicorn']}, 'foo.1')).to.eql(
+				{foo: [{ bar: 'gold-unicorn'}, 'silver-unicorn']}
+			);
+		});
+
+		it('Array element by $end', function() {
 			expect(dotProp.delete({foo: [{ bar: 'gold-unicorn'}, 'white-unicorn', 'silver-unicorn']}, 'foo.$end')).to.eql(
 				{foo: [{ bar: 'gold-unicorn'}, 'white-unicorn']}
 			);
 		});
 
+		it('Out of array', function() {
+			expect(dotProp.delete({foo: [{ bar: 'gold-unicorn'}, 'white-unicorn', 'silver-unicorn']}, 'foo.10')).to.eql(
+				{foo: [{ bar: 'gold-unicorn'}, 'white-unicorn', 'silver-unicorn']}
+			);
+		});
+
+		it('Array indexed by a property', function() {
+			try {
+				dotProp.delete({foo: [{ bar: 'gold-unicorn'}, 'white-unicorn', 'silver-unicorn']}, 'foo.bar');
+			} catch (err) {
+				expect(err).to.eql(new Error('Array index \'bar\' has to be an integer'));
+			}
+		});
+
 		it('Deep prop', function() {
 			expect(dotProp.delete({foo: [{ bar: 'gold-unicorn'}, 'white-unicorn', 'silver-unicorn']}, 'foo.0.bar')).to.eql(
 				{foo: [{}, 'white-unicorn', 'silver-unicorn']}