From 5b5a7c1350af7a28ff439dee37f57e9bacb31e6e Mon Sep 17 00:00:00 2001
From: Matt Chaffe <matt@mattchaffe.uk>
Date: Thu, 25 Apr 2019 17:24:09 +0100
Subject: [PATCH 1/4] Added initial docs for `push`

---
 doc/array/push.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/doc/array/push.md b/doc/array/push.md
index 17ba0ee..56b21ec 100644
--- a/doc/array/push.md
+++ b/doc/array/push.md
@@ -1,2 +1,46 @@
 @property {function} can-observe/push push
 @parent can-observe/array
+
+@description Add elements to the end of an observe array.
+@signature `list.push(...elements)`
+
+  `push` adds elements onto the end of an observe array.
+
+  ```js
+  import { observe } from "can/everything";
+
+  const names = new observe.Array(['Alice', 'Bob']);
+  names.push('Chris');
+
+  console.log(names); //-> ['Alice', 'Bob', 'Chris']
+  ```
+  @codepen
+
+  @param {*} elements the elements to add to the Array
+
+  @return {Number} the new length of the Array
+
+@body
+
+## Use
+
+If you wish to listen to changes on the array:
+
+```js
+import { observe, Reflect } from "can/everything";
+
+const birds = ['Buzzard', 'Sparrowhawk'];
+const list = observe(['Eagle']);
+
+Reflect.onPatches(list, function (data) {
+	console.log(data[0].insert) //-> ['Buzzard', 'Sparrowhawk']
+})
+
+list.push(...birds);
+console.log(list); // ['Buzzard', 'Sparrowhawk', 'Eagle']
+```
+@codepen
+
+## Events
+
+`push` causes _length_ events to be fired.

From 0a83effc5f251448b1cf303809f6e7e527bab934 Mon Sep 17 00:00:00 2001
From: Matt Chaffe <matt@mattchaffe.uk>
Date: Thu, 25 Apr 2019 19:00:10 +0100
Subject: [PATCH 2/4] Added remaining array method documentation

---
 doc/array/pop.md     | 22 ++++++++++++++++++++++
 doc/array/push.md    | 19 -------------------
 doc/array/reverse.md | 23 +++++++++++++++++++++++
 doc/array/shift.md   | 24 ++++++++++++++++++++++++
 doc/array/sort.md    | 34 ++++++++++++++++++++++++++++++++++
 doc/array/splice.md  | 44 ++++++++++++++++++++++++++++++++++++++++++++
 doc/array/unshift.md | 25 +++++++++++++++++++++++++
 7 files changed, 172 insertions(+), 19 deletions(-)

diff --git a/doc/array/pop.md b/doc/array/pop.md
index f71d45e..c64107d 100644
--- a/doc/array/pop.md
+++ b/doc/array/pop.md
@@ -1,2 +1,24 @@
 @property {function} can-observe/pop pop
 @parent can-observe/array
+
+@description Remove an element from the end of an observe array.
+@signature `list.pop()`
+
+  `pop` removes an element from then end of an observe array.
+
+  ```js
+  import { observe } from "can/everything";
+
+  const names = new observe.Array(['Alice', 'Bob']);
+
+  console.log(names.pop()); //-> ['Bob']
+  ```
+  @codepen
+
+  @return {*} The element from the end of the Array
+
+@body
+
+## Events
+
+`pop` causes _length_ events to be fired.
diff --git a/doc/array/push.md b/doc/array/push.md
index 56b21ec..ba80611 100644
--- a/doc/array/push.md
+++ b/doc/array/push.md
@@ -22,25 +22,6 @@
 
 @body
 
-## Use
-
-If you wish to listen to changes on the array:
-
-```js
-import { observe, Reflect } from "can/everything";
-
-const birds = ['Buzzard', 'Sparrowhawk'];
-const list = observe(['Eagle']);
-
-Reflect.onPatches(list, function (data) {
-	console.log(data[0].insert) //-> ['Buzzard', 'Sparrowhawk']
-})
-
-list.push(...birds);
-console.log(list); // ['Buzzard', 'Sparrowhawk', 'Eagle']
-```
-@codepen
-
 ## Events
 
 `push` causes _length_ events to be fired.
diff --git a/doc/array/reverse.md b/doc/array/reverse.md
index 56c05b3..9439ba8 100644
--- a/doc/array/reverse.md
+++ b/doc/array/reverse.md
@@ -1,2 +1,25 @@
 @property {function} can-observe/reverse reverse
 @parent can-observe/array
+
+@description Reverses the order of the observe array.
+@signature `list.reverse()`
+
+  `reverse` Reverses the order of the observe array in place.
+
+  ```js
+  import { observe } from "can/everything";
+
+  const names = new observe.Array(['Alice', 'Bob', 'Chris']);
+  names.reverse();
+
+  console.log(names); //-> ['Chris', 'Bob', 'Alice']
+  ```
+  @codepen
+
+  @return {can-observe.Array} The observe array with reverse ordered elements
+
+@body
+
+## Events
+
+`reverse` causes _length_ events to be fired.
diff --git a/doc/array/shift.md b/doc/array/shift.md
index 062b86a..3d3a307 100644
--- a/doc/array/shift.md
+++ b/doc/array/shift.md
@@ -1,2 +1,26 @@
 @property {function} can-observe/shift shift
 @parent can-observe/array
+
+@description Remove an element from the front of an observe array.
+@signature `list.shift()`
+
+  `shift` removes an element from the front of an observe array.
+
+  ```js
+  import { observe } from "can/everything";
+
+  const names = new observe.Array(['Alice', 'Bob', 'Chris']);
+  console.log(names.shift()); //-> 'Alice'
+  console.log(names.shift()); //-> 'Bob'
+  console.log(names.shift()); //-> 'Chris'
+  console.log(names.shift()); //-> undefined
+  ```
+  @codepen
+
+  @return {*} The element shifted off from the array, or `undefined` if the array is empty
+
+@body
+
+## Events
+
+`shift` causes _length_ events to be fired.
diff --git a/doc/array/sort.md b/doc/array/sort.md
index 0eeba7e..9c8d96e 100644
--- a/doc/array/sort.md
+++ b/doc/array/sort.md
@@ -1,2 +1,36 @@
 @property {function} can-observe/sort sort
 @parent can-observe/array
+
+@description Add elements to the end of an observe array.
+@signature `list.sort([compareFunction])`
+
+  `sort` sorts the elements in place and returns the newly sorted array. The API is the same as the native JavaScript `Array.prototype.sort` API.
+
+  ```js
+  import { observe } from "can/everything";
+
+  const names = new observe.Array(['Chris', 'Alice', 'Bob']);
+  
+  names.sort((a, b) => {
+	  if (a.name < b.name) {
+		  return -1;
+	  } else if (a.name > b.name) {
+		  return 1;
+	  } else {
+		  return 0;
+	  }
+  });
+
+  console.log(names); //-> ['Alice', 'Bob', 'Chris']
+  ```
+  @codepen
+
+  @param {function(a, b)} compareFunction Specifies a function that defines the sort order.
+
+  @return {can-observe.Array} The ordered Array
+
+@body
+
+## Events
+
+`sort` causes _length_ events to be fired.
diff --git a/doc/array/splice.md b/doc/array/splice.md
index f1743b8..25b60dd 100644
--- a/doc/array/splice.md
+++ b/doc/array/splice.md
@@ -1,2 +1,46 @@
 @property {function} can-observe/splice splice
 @parent can-observe/array
+
+@description Insert and remove elements from an observe array.
+@signature `list.splice(index[, howMany[, ...newItems]])`
+
+  `splice` inserts and removes elements from an observe array.
+
+  ```js
+  import { observe } from "can/everything";
+
+  const names = new observe.Array(['Alice', 'Bob', 'Chris']);
+  console.log(names.splice(0, 1)); //-> ['Alice']
+
+  console.log(names); //-> ['Bob', 'Chris']
+  ```
+  @codepen
+
+  @param {Number} Where to start removing or inserting elements
+
+  @param {Number} The number of elements to remove, if _howMany_ is not provided `splice` will remove all elements from the `index` to the end of the array.
+
+  @param {*} elements Items to insert into the array
+
+  @return {Array} The elements removed by the `splice`.
+
+@body
+
+## Use
+
+`splice` lets you remove and insert items into an observe array.
+This example shows replacing an item at a given index:
+
+```js
+import { observe } from "can/everything";
+
+const names = new observe.Array(['Alice', 'Bob', 'Chris']);
+console.log(names.splice(1, 1, 'Dave')); //-> ['Bob']
+
+console.log(names); //-> ['Alice', 'Bob', 'Chris']
+```
+@codepen
+
+## Events
+
+`splice` causes _length_ events to be fired.
diff --git a/doc/array/unshift.md b/doc/array/unshift.md
index e8ffa87..abd9c9f 100644
--- a/doc/array/unshift.md
+++ b/doc/array/unshift.md
@@ -1,2 +1,27 @@
 @property {function} can-observe/unshift unshift
 @parent can-observe/array
+
+@description Add elements to the start of an observe array.
+@signature `list.unshift(...elements)`
+
+  `unshift` adds elements onto the start of an observe array.
+
+  ```js
+  import { observe } from "can/everything";
+
+  const names = new observe.Array(['Alice', 'Bob']);
+  names.unshift('Chris');
+
+  console.log(names); //-> ['Chris', 'Alice', 'Bob']
+  ```
+  @codepen
+
+  @param {*} elements the elements to add to the Array
+
+  @return {Number} the new length of the Array
+
+@body
+
+## Events
+
+`unshift` causes _length_ events to be fired.

From 06368b974a4ff9e62ea1e529a23071acac416c28 Mon Sep 17 00:00:00 2001
From: Matt Chaffe <matt@mattchaffe.uk>
Date: Thu, 25 Apr 2019 19:46:23 +0100
Subject: [PATCH 3/4] Added links on missing docs to can-reflect docs which
 have the implementation

---
 doc/function/defineInstanceKey.md      | 2 ++
 doc/function/offInstanceBoundChange.md | 2 ++
 doc/function/offInstancePatches.md     | 2 ++
 doc/function/onInstanceBoundChange.md  | 2 ++
 doc/function/onInstancePatches.md      | 2 ++
 doc/object/offKeyValue.md              | 2 ++
 doc/object/offPatches.md               | 2 ++
 doc/object/symbols-isBound.md          | 2 ++
 doc/object/symbols-onKeyValue.md       | 2 ++
 doc/object/symbols-onPatches.md        | 2 ++
 10 files changed, 20 insertions(+)

diff --git a/doc/function/defineInstanceKey.md b/doc/function/defineInstanceKey.md
index a656688..dc1ab82 100644
--- a/doc/function/defineInstanceKey.md
+++ b/doc/function/defineInstanceKey.md
@@ -1,2 +1,4 @@
 @property {Symbol} can-observe/can.defineInstanceKey @can.defineInstanceKey
 @parent can-observe/function
+
+@description See [can-reflect.defineInstanceKey @@can.defineInstanceKey] 
diff --git a/doc/function/offInstanceBoundChange.md b/doc/function/offInstanceBoundChange.md
index 8e01bbe..927a516 100644
--- a/doc/function/offInstanceBoundChange.md
+++ b/doc/function/offInstanceBoundChange.md
@@ -1,2 +1,4 @@
 @property {Symbol} can-observe/can.offInstanceBoundChange @can.offInstanceBoundChange
 @parent can-observe/function
+
+@description See [can-reflect/observe.offInstanceBoundChange @@can.offInstanceBoundChange]
diff --git a/doc/function/offInstancePatches.md b/doc/function/offInstancePatches.md
index d9a50ad..eb83777 100644
--- a/doc/function/offInstancePatches.md
+++ b/doc/function/offInstancePatches.md
@@ -1,2 +1,4 @@
 @property {Symbol} can-observe/can.offInstancePatches @can.offInstancePatches
 @parent can-observe/function
+
+@description See [can-reflect/observe.offInstancePatches @@can.offInstancePatches]
diff --git a/doc/function/onInstanceBoundChange.md b/doc/function/onInstanceBoundChange.md
index e47888f..59a9dd1 100644
--- a/doc/function/onInstanceBoundChange.md
+++ b/doc/function/onInstanceBoundChange.md
@@ -1,2 +1,4 @@
 @property {Symbol} can-observe/can.onInstanceBoundChange @can.onInstanceBoundChange
 @parent can-observe/function
+
+@description See [can-reflect/observe.onInstanceBoundChange @@can.onInstanceBoundChange]
diff --git a/doc/function/onInstancePatches.md b/doc/function/onInstancePatches.md
index bd434fd..5cd0c98 100644
--- a/doc/function/onInstancePatches.md
+++ b/doc/function/onInstancePatches.md
@@ -1,2 +1,4 @@
 @property {Symbol} can-observe/can.onInstancePatches @can.onInstancePatches
 @parent can-observe/function
+
+@description See [can-reflect/observe.onInstancePatches @@can.onInstancePatches]
diff --git a/doc/object/offKeyValue.md b/doc/object/offKeyValue.md
index 5678ff3..840c7f1 100644
--- a/doc/object/offKeyValue.md
+++ b/doc/object/offKeyValue.md
@@ -1,2 +1,4 @@
 @property {Symbol} can-observe/can.offKeyValue @can.offKeyValue
 @parent can-observe/object
+
+@description See [can-reflect/observe.offKeyValue @@can.offKeyValue]
diff --git a/doc/object/offPatches.md b/doc/object/offPatches.md
index c88c733..ebaad10 100644
--- a/doc/object/offPatches.md
+++ b/doc/object/offPatches.md
@@ -1,2 +1,4 @@
 @property {Symbol} can-observe/can.offPatches @can.offPatches
 @parent can-observe/object
+
+@description See [can-reflect/observe.offPatches @@can.offPatches]
diff --git a/doc/object/symbols-isBound.md b/doc/object/symbols-isBound.md
index aa4ba5e..e808eaa 100644
--- a/doc/object/symbols-isBound.md
+++ b/doc/object/symbols-isBound.md
@@ -1,2 +1,4 @@
 @property {Symbol} can-observe/can.isBound @can.isBound
 @parent can-observe/object
+
+@description See [can-reflect/observe.isBound @@can.isBound]
diff --git a/doc/object/symbols-onKeyValue.md b/doc/object/symbols-onKeyValue.md
index a4d4c32..7f19fdc 100644
--- a/doc/object/symbols-onKeyValue.md
+++ b/doc/object/symbols-onKeyValue.md
@@ -1,2 +1,4 @@
 @property {Symbol} can-observe/can.onKeyValue @can.onKeyValue
 @parent can-observe/object
+
+@description See [can-reflect/observe.onKeyValue @@can.onKeyValue]
diff --git a/doc/object/symbols-onPatches.md b/doc/object/symbols-onPatches.md
index aafd27e..dd1f818 100644
--- a/doc/object/symbols-onPatches.md
+++ b/doc/object/symbols-onPatches.md
@@ -1,2 +1,4 @@
 @property {Symbol} can-observe/can.onPatches @can.onPatches
 @parent can-observe/object
+
+@description See [can-reflect/observe.onPatches @@can.onPatches]

From 409002f2c1ea35ed68001140d4f5b73bac14e559 Mon Sep 17 00:00:00 2001
From: Matt Chaffe <matt@mattchaffe.uk>
Date: Thu, 25 Apr 2019 21:52:35 +0100
Subject: [PATCH 4/4] Improve documentation after feedback

---
 doc/array/pop.md     | 2 +-
 doc/array/reverse.md | 4 ++--
 doc/array/shift.md   | 4 ++--
 doc/array/sort.md    | 6 +++---
 doc/array/splice.md  | 6 +++---
 5 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/doc/array/pop.md b/doc/array/pop.md
index c64107d..0dc4a07 100644
--- a/doc/array/pop.md
+++ b/doc/array/pop.md
@@ -4,7 +4,7 @@
 @description Remove an element from the end of an observe array.
 @signature `list.pop()`
 
-  `pop` removes an element from then end of an observe array.
+  `pop` removes the last element from the array.
 
   ```js
   import { observe } from "can/everything";
diff --git a/doc/array/reverse.md b/doc/array/reverse.md
index 9439ba8..5cc02ef 100644
--- a/doc/array/reverse.md
+++ b/doc/array/reverse.md
@@ -4,7 +4,7 @@
 @description Reverses the order of the observe array.
 @signature `list.reverse()`
 
-  `reverse` Reverses the order of the observe array in place.
+  `reverse` reverses the order of the array in place.
 
   ```js
   import { observe } from "can/everything";
@@ -16,7 +16,7 @@
   ```
   @codepen
 
-  @return {can-observe.Array} The observe array with reverse ordered elements
+  @return {can-observe.Array} The array with reverse ordered elements
 
 @body
 
diff --git a/doc/array/shift.md b/doc/array/shift.md
index 3d3a307..c3bc187 100644
--- a/doc/array/shift.md
+++ b/doc/array/shift.md
@@ -1,10 +1,10 @@
 @property {function} can-observe/shift shift
 @parent can-observe/array
 
-@description Remove an element from the front of an observe array.
+@description Removes the first element from an array.
 @signature `list.shift()`
 
-  `shift` removes an element from the front of an observe array.
+  `shift` removes an element from the front of an array.
 
   ```js
   import { observe } from "can/everything";
diff --git a/doc/array/sort.md b/doc/array/sort.md
index 9c8d96e..d6da5b6 100644
--- a/doc/array/sort.md
+++ b/doc/array/sort.md
@@ -1,10 +1,10 @@
 @property {function} can-observe/sort sort
 @parent can-observe/array
 
-@description Add elements to the end of an observe array.
+@description Sort the elements in an array.
 @signature `list.sort([compareFunction])`
 
-  `sort` sorts the elements in place and returns the newly sorted array. The API is the same as the native JavaScript `Array.prototype.sort` API.
+  `sort` sorts the elements in place and returns the sorted array. The API is the same as the native [sort](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) API.
 
   ```js
   import { observe } from "can/everything";
@@ -27,7 +27,7 @@
 
   @param {function(a, b)} compareFunction Specifies a function that defines the sort order.
 
-  @return {can-observe.Array} The ordered Array
+  @return {can-observe.Array} The ordered array
 
 @body
 
diff --git a/doc/array/splice.md b/doc/array/splice.md
index 25b60dd..faa60c1 100644
--- a/doc/array/splice.md
+++ b/doc/array/splice.md
@@ -16,11 +16,11 @@
   ```
   @codepen
 
-  @param {Number} Where to start removing or inserting elements
+  @param {Number} index Where to start removing or inserting elements
 
-  @param {Number} The number of elements to remove, if _howMany_ is not provided `splice` will remove all elements from the `index` to the end of the array.
+  @param {Number} howMany The number of elements to remove, if _howMany_ is not provided `splice` will remove all elements from the `index` to the end of the array.
 
-  @param {*} elements Items to insert into the array
+  @param {*} newItems Items to insert into the array
 
   @return {Array} The elements removed by the `splice`.