Index: lib/typedObjects.js
===================================================================
--- a/lib/typedObjects.js
+++ b/lib/typedObjects.js
@@ -150,16 +150,23 @@
  *    get(index): retrieves the array element at specified index.
  *    set(index, value): sets the array element at specified index.
  *    length: number of elements in the array, by default 0. Increase the length
  *        to match your data size.
  *    size: size of the allocated buffer in array elements, will be at least
  *        equal to length. Normally you won't need to set the size explicitly.
  *        However, the size won't decrease automatically if the array gets
  *        smaller so you might want to set it in order to shrink the array.
+ *    splice(), push(), pop(), unshift(), shift(): these work the same as the
+ *        corresponding methods on JavaScript's Array class. Note however that
+ *        using pop() and shift() with arrays of objects is dangerous if you
+ *        want to work with their return value: this operation will call
+ *        release() on the resulting object before returning which might result
+ *        in it being garbage collected. You should call retain() on the array
+ *        element before calling pop() or shift().
  *
  * String type
  * -----------
  *
  * There is a special array type called string:
  *
  *    var str1 = string();            // empty string
  *    var str2 = string(2);           // "\0\0"