Merge pull request #1 from BloomBooks/JohnChanges

Enhance class comments

src/bubble.ts

@@ -2,7 +2,16 @@ import { Path, Point, Color, ToolEvent, Item, Shape, project } from "paper";
 import { BubbleSpec, Tip } from "bubbleSpec";
 import Comical from "./comical";
 
-// This class should represent a bubble (including the tail) and the methods for drawing a single bubble
+// This class represents a bubble (including the tails, if any) wrapped around an HTML element
+// and handles
+// - storing and retrieving the BubbleSpec that represents the persistent state of
+// the Bubble from the element's data-bubble attribute;
+// - creating paper.js shapes representing the bubble and tails
+// - positioning and sizing those shapes based on the position and size of the wrapped element
+// - automatically repostioning them when the wrapped element changes (ToDo)
+// - creating handles on the tails to allow the user to drag them, and updating
+// the data-bubble as well as the paper.js shapes when this happens
+// - allowing the Bubble to be dragged, and updating the wrapped element's position (ToDo)
 export default class Bubble {
   public content: HTMLElement;
   // TODO: What is the best name for "spec"?

src/bubbleSpec.ts

@@ -1,8 +1,13 @@
 // This is the interface for storing the state of a bubble.
 
-// BubblePattern actually defines all the Bubble properties, but
+// BubbleSpecPattern actually defines all the BubbleSpec properties, but
 // all of them are optional, for use in methods designed to allow a subset
-// of properties to be changed. Bubble overrides to make a minimal set required.
+// of properties to be changed. BubbleSpec overrides to make a minimal set required.
+// The main purpose of this class is to store the state of a bubble in a modified JSON
+// string in the data-bubble attribute of an HTML element. See the Bubble methods
+// setBubbleSpec and getBubbleSpec. This allows re-creatting the paper.js editable
+// state of the bubble even after we have discarded all that in favor of an SVG
+// for a finished HTML document that doesn't depend on Javascript.
 export interface BubbleSpecPattern {
   version?: string; // currently 1.0
   style?: string; // currently one of speech or shout

src/comical.ts

@@ -3,7 +3,22 @@ import { Path, Point, Color, Item, project, setup } from "paper";
 import Bubble from "./bubble";
 import { uniqueIds } from "./uniqueId";
 
-// Manages all the bubbles
+// Manages a collection of comic bubbles warpped around HTML elements that share a common parent.
+// Each element that has a comic bubble has a data-bubble attribute specifying the appearance
+// of the bubble. Comical can help with initializing this to add a bubble to an element.
+// The data-bubble attributes contain a modified JSON representation of a BubbleSpec
+// describing the bubble.
+// Comical is designed to be the main class exported by Comical.js, and provides methods
+// for setting things up (using a canvas overlayed on the common parent of the bubbles
+// and paper.js shapes) so that the bubbles can be edited by dragging handles.
+// It also supports drawing groups of bubbles in layers, with appropriate merging
+// of bubbles at the same level.
+// As the bubbles are edited using Comical handles, the data-bubble attributes are
+// automatically updated. It's also possible to alter a data-bubble attribute using
+// external code, and tell Comical to update things to match.
+// Finally, Comical can replace a finished bubble canvas with a single SVG, resulting in
+// a visually identical set of bubbles that can be rendered without using Canvas and
+// Javascript.
 export default class Comical {
   static backColor = new Color("white");