Merge pull request #79 from canjs/documentation-array

Adding documentation for missing observe methods

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 the last element from the 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.

doc/array/push.md

@@ -1,2 +1,27 @@
 @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
+
+## Events
+
+`push` causes _length_ events to be fired.

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 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 array with reverse ordered elements
+
+@body
+
+## Events
+
+`reverse` causes _length_ events to be fired.

doc/array/shift.md

@@ -1,2 +1,26 @@
 @property {function} can-observe/shift shift
 @parent can-observe/array
+
+@description Removes the first element from an array.
+@signature `list.shift()`
+
+  `shift` removes an element from the front of an 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.

doc/array/sort.md

@@ -1,2 +1,36 @@
 @property {function} can-observe/sort sort
 @parent can-observe/array
+
+@description Sort the elements in an array.
+@signature `list.sort([compareFunction])`
+
+  `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";
+
+  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.

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} index Where to start removing or inserting elements
+
+  @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 {*} newItems 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.

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.

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] 

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]

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]

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]

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]

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]

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]

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]

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]

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]