Add a README file and license

LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2017 by Marijn Haverbeke <marijnh@gmail.com> and others
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,77 @@
+# prosemirror-changeset
+
+This is a helper module that can turn a sequence of document changes
+into a set of insertions and deletions, for example to display them in
+a change-tracking interface. Such a set can be built up incrementally,
+in order to do such change tracking in a halfway performant way during
+live editing.
+
+This code is licensed under an [MIT
+licence](https://github.com/ProseMirror/prosemirror-changeset/blob/master/LICENSE).
+
+## Programming interface
+
+Insertions and deletions are represented as ‘spans’—ranges in the
+document. The deleted spans refer to the original document, whereas
+the inserted ones point into the current document.
+
+It is possible to associate arbitrary data values with such spans, for
+example to track the user that made the change, the timestamp at which
+it was made, or the step data necessary to invert it again.
+
+### class Span
+
+A document range with metadata associated with it. Used to
+track both inserted and deleted ranges, though deletions are
+represented with a subclass.
+
+ * **`from`**`: number`\
+   The start of this span.
+
+ * **`to`**`: number`\
+   The end of the span.
+
+ * **`data`**`: any`\
+   Data associated with this span.
+
+
+### class DeletedSpan extends Span
+
+Used to represent a deletion.
+
+ * **`pos`**`: number`\
+   The position of the deletion in the current document.
+
+ * **`slice`**`: Slice`\
+   The deleted content.
+
+
+### class ChangeSet
+
+An changeset tracks the changes to a document from a given
+point in the past. It condenses a number of step maps down to a
+flat sequence of insertions and deletions, and merges adjacent
+insertions/deletions that (partially) undo each other.
+
+ * **`inserted`**`: [Span]`\
+   Inserted regions. Their `from`/`to` point into the current
+   document.
+
+ * **`deleted`**`: [DeletedSpan]`\
+   Deleted ranges. Their `from`/`to` point into the old document,
+   and their `pos` into the new.
+
+ * **`addSteps`**`(newDoc: Node, maps: [StepMap], data: [any] | any) → ChangeSet`\
+   Computes a new changeset by adding the given step maps and
+   metadata (either as an array, per-map, or as a single value to be
+   associated with all maps) to the current set. Will not mutate the
+   old set.
+
+ * `static `**`create`**`(doc: Node, ?Object = {}) → ChangeSet`\
+   Create a changeset with the given base object and
+   configuration. The `compare` and `combine` options should be
+   functions, and are used to compare and combine metadata—`compare`
+   determines whether two spans are compatible, and when they are,
+   `combine` will compute the metadata value for the merged span.
+
+

package.json

@@ -29,6 +29,7 @@
     "test": "mocha test/test-*.js",
     "build": "rollup -c",
     "watch": "rollup -c -w",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "build-readme": "builddocs --name changeset --main src/README.md --format markdown src/*.js > README.md"
   }
 }

src/README.md

@@ -0,0 +1,26 @@
+# prosemirror-changeset
+
+This is a helper module that can turn a sequence of document changes
+into a set of insertions and deletions, for example to display them in
+a change-tracking interface. Such a set can be built up incrementally,
+in order to do such change tracking in a halfway performant way during
+live editing.
+
+This code is licensed under an [MIT
+licence](https://github.com/ProseMirror/prosemirror-changeset/blob/master/LICENSE).
+
+## Programming interface
+
+Insertions and deletions are represented as ‘spans’—ranges in the
+document. The deleted spans refer to the original document, whereas
+the inserted ones point into the current document.
+
+It is possible to associate arbitrary data values with such spans, for
+example to track the user that made the change, the timestamp at which
+it was made, or the step data necessary to invert it again.
+
+@Span
+
+@DeletedSpan
+
+@ChangeSet

src/changeset.js

@@ -13,9 +13,9 @@ export class DeletedSpan extends Span {
   }
 }
 
-// ::- An edit set tracks the changes to a document from a given point
-// in the past. It condenses a number of step maps down to a flat
-// sequence of insertions and deletions, and merges adjacent
+// ::- An changeset tracks the changes to a document from a given
+// point in the past. It condenses a number of step maps down to a
+// flat sequence of insertions and deletions, and merges adjacent
 // insertions/deletions that (partially) undo each other.
 export class ChangeSet {
   constructor(config, maps, inserted, deleted) {
@@ -32,7 +32,7 @@ export class ChangeSet {
   }
 
   // :: (Node, [StepMap], union<[any], any>) → ChangeSet
-  // Computes a new edit set by adding the given step maps and
+  // Computes a new changeset by adding the given step maps and
   // metadata (either as an array, per-map, or as a single value to be
   // associated with all maps) to the current set. Will not mutate the
   // old set.
@@ -148,7 +148,7 @@ export class ChangeSet {
   }
 
   // :: (Node, ?Object) → ChangeSet
-  // Create a new edit set with the given base object and
+  // Create a changeset with the given base object and
   // configuration. The `compare` and `combine` options should be
   // functions, and are used to compare and combine metadata—`compare`
   // determines whether two spans are compatible, and when they are,

src/span.js

@@ -3,11 +3,11 @@
 // represented with a subclass.
 export class Span {
   constructor(from, to, data) {
-    // :: number
+    // :: number The start of this span.
     this.from = from
-    // :: number
+    // :: number The end of the span.
     this.to = to
-    // :: any
+    // :: any Data associated with this span.
     this.data = data
   }
 }