Documentation improvements

Author: mscuthbert

src/element.ts

@@ -64,6 +64,9 @@ export abstract class Element {
     return Category.Element;
   }
 
+  // all Element objects keep a list of children that they are responsible and which
+  // inherit the style of their parents.
+  // Currently used by StaveNote for noteheads and
   protected children: Element[] = [];
   protected static ID: number = 1000;
   protected static newID(): string {
@@ -108,6 +111,15 @@ export abstract class Element {
     Registry.getDefaultRegistry()?.register(this);
   }
 
+  /**
+   * Adds a child Element to the Element, which lets it inherit the
+   * same style as the parent when setGroupStyle() is called.
+   *
+   * Examples of children are noteheads and stems.  Modifiers such
+   * as Accidentals are generally not set as children.
+   *
+   * Note that StaveNote calls setGroupStyle() when setStyle() is called.
+   */
   addChildElement(child: Element): this {
     this.children.push(child);
     return this;
@@ -186,7 +198,7 @@ export abstract class Element {
 
   /**
    * Draw the element and all its sub-elements (ie.: Modifiers in a Stave)
-   * with the element style.
+   * with the element's style (see `getStyle()` and `setStyle()`)
    */
   drawWithStyle(): void {
     this.checkContext();

src/glyphnote.ts

@@ -1,4 +1,6 @@
 // [VexFlow](https://vexflow.com) - Copyright (c) Mohit Muthanna 2010.
+//
+// Any glyph that is set to appear on a Stave and take up musical time and graphical space.
 
 import { BoundingBox } from './boundingbox';
 import { Glyph } from './glyph';

src/modifiercontext.ts

@@ -3,7 +3,12 @@
 // ## Description
 //
 // This class implements various types of members to notes (e.g. bends,
-// fingering positions etc.)
+// fingering positions etc.).  The ModifierContext works with tickables
+// that are at the same tick to ensure that they and their modifiers
+// all have proper alignment.  (Note that the ModifierContext also
+// runs the spacing of the tickable).
+//
+// see https://github.com/0xfe/vexflow/wiki/How-Formatting-Works
 
 import { Accidental } from './accidental';
 import { Annotation } from './annotation';
@@ -58,7 +63,8 @@ export class ModifierContext {
     top_text_line: 0,
   };
 
-  // Current members
+  // Current members -- a mapping of Category (string) to a list of Tickables, Modifiers,
+  // StaveNotes, TabNotes, etc.
   protected members: Record<string, ModifierContextMember[]> = {};
 
   protected preFormatted: boolean = false;
@@ -102,6 +108,9 @@ export class ModifierContext {
     return this.members[category] ?? [];
   }
 
+  /**
+   * Get the width of the entire
+   */
   getWidth(): number {
     return this.width;
   }

src/tickable.ts

@@ -205,13 +205,13 @@ export abstract class Tickable extends Element {
     return this.tuplet;
   }
 
-  /** Return the intrinsic ticks. */
+  /** Return a list of Tuplets. */
   getTupletStack(): Tuplet[] {
     return this.tupletStack;
   }
 
   /**
-   * Reset the specific Tuplet if this is not provided, all tuplets are reset.
+   * Reset the specific Tuplet (if this is not provided, all tuplets are reset).
    * Remove any prior tuplets from the tick calculation and
    * reset the intrinsic tick value.
    */