[CLEANUP] Improve documentation for Editor, Post, PostNodeBuilder, Range

Author: bantic

src/js/editor/editor.js

@@ -78,21 +78,22 @@ const CALLBACK_QUEUES = {
   DID_REPARSE: 'didReparse'
 };
 
+/**
+ * The Editor is a core component of mobiledoc-kit. After instantiating 
+ * an editor, use {@link Editor#render} to display the editor on the web page.
+ *
+ * An editor uses a {@link Post} internally to represent the displayed document.
+ * The post can be serialized as mobiledoc using {@link Editor#serialize}. Mobiledoc
+ * is the transportable "over-the-wire" format (JSON) that is suited for persisting
+ * and sharing between editors and renderers (for display, e.g.), whereas the Post
+ * model is better suited for programmatic editing.
+ *
+ * The editor will call registered callbacks for certain state changes. These are:
+ *   * cursorDidChange
+ *   * didUpdate
+ */
 class Editor {
   /**
-   * The Editor is a core component of mobiledoc-kit. After instantiating 
-   * an editor, use {@link Editor#render} to display the editor on the web page.
-   *
-   * An editor uses a {@link Post} internally to represent the displayed document.
-   * The post can be serialized as mobiledoc using {@link Editor#serialize}. Mobiledoc
-   * is the transportable "over-the-wire" format (JSON) that is suited for persisting
-   * and sharing between editors and renderers (for display, e.g.), whereas the Post
-   * model is better suited for programmatic editing.
-   *
-   * The editor will call registered callbacks for certain state changes. These are:
-   *   * cursorDidChange
-   *   * didUpdate
-   *
    * @param {Object} [options]
    * @param {Object} [options.mobiledoc] The mobiledoc to load into the editor.
    *        Supersedes `options.html`.
@@ -142,10 +143,10 @@ class Editor {
     this.hasRendered = false;
   }
 
-  addView(view) {
-    this._views.push(view);
-  }
-
+  /**
+   * The editor's instance of a post node builder.
+   * @type {PostNodeBuilder}
+   */
   get builder() {
     if (!this._builder) { this._builder = new PostNodeBuilder(); }
     return this._builder;
@@ -446,7 +447,7 @@ class Editor {
   }
 
   /**
-   * @return {array} The sections from the cursor's selection start to the selection end
+   * @return {Section[]} The sections from the cursor's selection start to the selection end
    */
   get activeSections() {
     return this._editState.activeSections;
@@ -468,6 +469,10 @@ class Editor {
     return this._editState.activeMarkups;
   }
 
+  /**
+   * @param {Markup|String} markup A markup instance, or a string (e.g. "b")
+   * @return {boolean}
+   */
   hasActiveMarkup(markup) {
     markup = this.builder._coerceMarkup(markup);
     return contains(this.activeMarkups, markup);
@@ -479,10 +484,9 @@ class Editor {
   }
 
   /**
-   * @public
-   *
-   * @param {string} version The mobiledoc version to serialize to.
+   * @param {String} version The mobiledoc version to serialize to.
    * @return {Mobiledoc} Serialized mobiledoc
+   * @public
    */
   serialize(version=MOBILEDOC_VERSION) {
     return this.serializePost(this.post, 'mobiledoc', {version});
@@ -537,6 +541,10 @@ class Editor {
     }
   }
 
+  addView(view) {
+    this._views.push(view);
+  }
+
   removeAllViews() {
     this._views.forEach((v) => v.destroy());
     this._views = [];
@@ -704,7 +712,7 @@ class Editor {
   }
 
   /**
-   * @param {Function} callback This callback will be called after the cursor
+   * @param {Function} callback This callback will be called every time the cursor
    *        position (or selection) changes.
    * @public
    */
@@ -772,6 +780,16 @@ class Editor {
     });
   }
 
+  /**
+   * Toggles the given markup at the editor's current {@link Range}.
+   * If the range is collapsed this changes the editor's state so that the
+   * next characters typed will be affected. If there is text selected
+   * (aka a non-collapsed range), the selections' markup will be toggled.
+   * If the editor is not focused and has no active range, nothing happens.
+   * @param {String} markup E.g. "b", "em", "a"
+   * @public
+   * @see PostEditor#toggleMarkup
+   */
   toggleMarkup(markup) {
     markup = this.post.builder.createMarkup(markup);
     if (this.range.isCollapsed) {
@@ -822,6 +840,12 @@ class Editor {
     return false;
   }
 
+  /**
+   * Inserts the text at the current cursor position. If the editor has
+   * no current cursor position, nothing will be inserted.
+   * @param {String} text
+   * @public
+   */
   insertText(text) {
     let { activeMarkups, range, range: { head: position } } = this;
 
@@ -859,6 +883,22 @@ class Editor {
   triggerEvent(context, eventName, event) {
     this._eventManager._trigger(context, eventName, event);
   }
+
+  addCallback(...args) {
+    this._callbacks.addCallback(...args);
+  }
+
+  addCallbackOnce(...args) {
+    this._callbacks.addCallbackOnce(...args);
+  }
+
+  runCallbacks(...args) {
+    if (this._isDestroyed) {
+      // warn -- should not run after destroyed
+      return;
+    }
+    this._callbacks.runCallbacks(...args);
+  }
 }
 
 mixin(Editor, EventEmitter);

src/js/editor/post.js

@@ -18,21 +18,22 @@ const CALLBACK_QUEUES = {
   AFTER_COMPLETE: 'afterComplete'
 };
 
+/**
+ * The PostEditor is used to modify a post. It should not be instantiated directly.
+ * Instead, a new instance of a PostEditor is created by the editor and passed
+ * as the argument to the callback in {@link Editor#run}.
+ *
+ * Usage:
+ * ```
+ * editor.run((postEditor) => {
+ *   // postEditor is an instance of PostEditor that can operate on the
+ *   // editor's post
+ * });
+ * ```
+ */
 class PostEditor {
   /**
-   * The PostEditor is used to modify a post. It should not be instantiated directly.
-   * Instead, a new instance of a PostEditor is created by the editor and passed
-   * as the argument to the callback in {@link Editor#run}.
-   *
-   * Usage:
-   * ```
-   * editor.run((postEditor) => {
-   *   // postEditor is an instance of PostEditor that can operate on the
-   *   // editor's post
-   * });
-   * ```
-   * @param {Editor} editor
-   * @class PostEditor
+   * @private
    */
   constructor(editor) {
     this.editor = editor;

src/js/models/post-node-builder.js

@@ -34,11 +34,25 @@ function findMarkupInCache(cache, tagName, attributes) {
   return cache[key];
 }
 
-export default class PostNodeBuilder {
+/**
+ * The PostNodeBuilder is used to create new {@link Post} primitives, such
+ * as a MarkupSection, a CardSection, a Markup, etc. Every instance of an
+ * {@link Editor} has its own builder instance. The builder can be used
+ * inside an {@link Editor#run} callback to programmatically create new
+ * Post primitives to insert into the document.
+ * A PostNodeBuilder should be read from the Editor, *not* instantiated on its own.
+ */
+class PostNodeBuilder {
+  /**
+   * @private
+   */
   constructor() {
     this.markupCache = {};
   }
 
+  /**
+   * @return {Post} A new, blank post
+   */
   createPost(sections=[]) {
     const post = new Post();
     post.builder = this;
@@ -59,6 +73,11 @@ export default class PostNodeBuilder {
     }
   }
 
+  /**
+   * @param {tagName} [tagName='P']
+   * @param {Marker[]} [markers=[]]
+   * @return {MarkupSection}
+   */
   createMarkupSection(tagName=DEFAULT_MARKUP_SECTION_TAG_NAME, markers=[], isGenerated=false) {
     tagName = normalizeTagName(tagName);
     const section = new MarkupSection(tagName, markers);
@@ -91,26 +110,45 @@ export default class PostNodeBuilder {
     return section;
   }
 
+  /**
+   * @param {String} name
+   * @param {Object} [payload={}]
+   * @return {CardSection}
+   */
   createCardSection(name, payload={}) {
     const card = new Card(name, payload);
     card.builder = this;
     return card;
   }
 
+  /**
+   * @param {String} value
+   * @param {Markup[]} [markups=[]]
+   * @return {Marker}
+   */
   createMarker(value, markups=[]) {
     const marker = new Marker(value, markups);
     marker.builder = this;
     return marker;
   }
 
+  /**
+   * @param {String} name
+   * @param {String} [text='']
+   * @param {Object} [payload={}]
+   * @param {Markup[]} [markups=[]]
+   * @return {Atom}
+   */
   createAtom(name, text='', payload={}, markups=[]) {
     const atom = new Atom(name, text, payload, markups);
     atom.builder = this;
     return atom;
   }
 
   /**
-   * @param {Object} attributes {key:value}
+   * @param {String} tagName
+   * @param {Object} attributes Key-value pairs of attributes for the markup
+   * @return {Markup}
    */
   createMarkup(tagName, attributes={}) {
     tagName = normalizeTagName(tagName);
@@ -128,9 +166,12 @@ export default class PostNodeBuilder {
   /**
    * @param {Markup|String} markupOrString
    * @return {Markup}
+   * @private
    */
   _coerceMarkup(markupOrString, attributes={}) {
     let tagName = typeof markupOrString === 'string' ? markupOrString : markupOrString.tagName;
     return this.createMarkup(tagName, attributes);
   }
 }
+
+export default PostNodeBuilder;

src/js/models/post.js

@@ -14,9 +14,11 @@ import deprecate from 'mobiledoc-kit/utils/deprecate';
  * text) or non-markerable (e.g., a card).
  * When persisting a post, it must first be serialized (loss-lessly) into
  * mobiledoc using {@link Editor#serialize}.
- * @class Post
  */
-export default class Post {
+class Post {
+  /**
+   * @private
+   */
   constructor() {
     this.type = POST_TYPE;
     this.sections = new LinkedList({
@@ -284,3 +286,5 @@ export default class Post {
     return post;
   }
 }
+
+export default Post;

src/js/parsers/dom.js

@@ -89,10 +89,11 @@ function walkMarkerableNodes(parent, callback) {
   }
 }
 
-export default class DOMParser {
-  /**
-   * Parses DOM element -> Post
-   */
+/**
+ * Parses DOM element -> Post
+ * @private
+ */
+class DOMParser {
   constructor(builder, options={}) {
     this.builder = builder;
     this.sectionParser = new SectionParser(this.builder, options);
@@ -299,3 +300,5 @@ export default class DOMParser {
     }
   }
 }
+
+export default DOMParser;

src/js/parsers/section.js

@@ -44,11 +44,12 @@ const SKIPPABLE_ELEMENT_TAG_NAMES = [
   'style', 'head', 'title', 'meta'
 ].map(normalizeTagName);
 
-export default class SectionParser {
-  /**
-   * parses an element into a section, ignoring any non-markup
-   * elements contained within
-   */
+/**
+ * parses an element into a section, ignoring any non-markup
+ * elements contained within
+ * @private
+ */
+class SectionParser {
   constructor(builder, options={}) {
     this.builder = builder;
     this.plugins = options.plugins || [];
@@ -302,3 +303,5 @@ export default class SectionParser {
                     normalizeTagName(element.tagName)));
   }
 }
+
+export default SectionParser;