bring insert method inline with transform callback, add docs

before the insertPartsAt method would call the update callback
on its own, but now we have the concept of a transformation session,
so lets bring the API in line

src/editor/range.js

@@ -41,6 +41,12 @@ export default class Range {
         return text;
     }
 
+    /**
+     * Splits the model at the range boundaries and replaces with the given parts.
+     * Should be run inside a `model.transform()` callback.
+     * @param {Part[]} parts the parts to replace the range with
+     * @return {Number} the net amount of characters added, can be negative.
+     */
     replace(parts) {
         const newLength = parts.reduce((sum, part) => sum + part.text.length, 0);
         let oldLength = 0;