Merge pull request #1514 from 0xfe/doc_improvements

A few doc clarifications

Author: rvilarl

src/element.ts

@@ -58,12 +58,19 @@ export interface ElementStyle {
 /**
  * Element implements a generic base class for VexFlow, with implementations
  * of general functions and properties that can be inherited by all VexFlow elements.
+ *
+ * The Element is an abstract class that needs to be subclassed to work. It handles
+ * style and text-font properties for the Element and any child elements, along with
+ * working with the Registry to create unique ids, but does not have any tools for
+ * formatting x or y positions or connections to a Stave.
  */
 export abstract class Element {
   static get CATEGORY(): string {
     return Category.Element;
   }
 
+  // all Element objects keep a list of children that they are responsible and which
+  // inherit the style of their parents.
   protected children: Element[] = [];
   protected static ID: number = 1000;
   protected static newID(): string {
@@ -108,6 +115,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 +202,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();
@@ -258,7 +274,7 @@ export abstract class Element {
     return this.attrs;
   }
 
-  /** Return an attribute. */
+  /** Return an attribute, such as 'id', 'type' or 'class'. */
   // eslint-disable-next-line
   getAttribute(name: string): any {
     return this.attrs[name];
@@ -271,7 +287,7 @@ export abstract class Element {
     if (element) return element as unknown as SVGElement;
   }
 
-  /** Set an attribute. */
+  /** Set an attribute such as 'id', 'class', or 'type'. */
   setAttribute(name: string, value: string | undefined): this {
     const oldID = this.attrs.id;
     const oldValue = this.attrs[name];
@@ -286,18 +302,18 @@ export abstract class Element {
     return this.boundingBox;
   }
 
-  /** Return the context. */
+  /** Return the context, such as an SVGContext or CanvasContext object. */
   getContext(): RenderContext | undefined {
     return this.context;
   }
 
-  /** Set the context. */
+  /** Set the context to an SVGContext or CanvasContext object */
   setContext(context?: RenderContext): this {
     this.context = context;
     return this;
   }
 
-  /** Validate and return the context. */
+  /** Validate and return the rendering context. */
   checkContext(): RenderContext {
     return defined(this.context, 'NoContext', 'No rendering context attached to instance.');
   }
@@ -306,19 +322,24 @@ export abstract class Element {
   // Font Handling
 
   /**
-   * Provide a CSS compatible font string (e.g., 'bold 16px Arial').
+   * Provide a CSS compatible font string (e.g., 'bold 16px Arial') that will be applied
+   * to text (not glyphs).
    */
   set font(f: string) {
     this.setFont(f);
   }
 
-  /** Returns the CSS compatible font string. */
+  /** Returns the CSS compatible font string for the text font. */
   get font(): string {
     return Font.toCSSString(this.textFont);
   }
 
   /**
-   * Set the element's font family, size, weight, style (e.g., `Arial`, `10pt`, `bold`, `italic`).
+   * Set the element's text font family, size, weight, style
+   * (e.g., `Arial`, `10pt`, `bold`, `italic`).
+   *
+   * This attribute does not determine the font used for musical Glyphs like treble clefs.
+   *
    * @param font is 1) a `FontInfo` object or
    *                2) a string formatted as CSS font shorthand (e.g., 'bold 10pt Arial') or
    *                3) a string representing the font family (at least one of `size`, `weight`, or `style` must also be provided).
@@ -364,6 +385,10 @@ export abstract class Element {
     return this;
   }
 
+  /**
+   * Get the css string describing this Element's text font. e.g.,
+   * 'bold 10pt Arial'.
+   */
   getFont(): string {
     if (!this.textFont) {
       this.resetFont();

src/formatter.ts

@@ -16,7 +16,7 @@ import { TabStave } from './tabstave';
 import { Tickable } from './tickable';
 import { TickContext } from './tickcontext';
 import { isNote, isStaveNote } from './typeguard';
-import { defined, log, midLine, RuntimeError } from './util';
+import { defined, log, midLine, RuntimeError, sumArray } from './util';
 import { Voice } from './voice';
 
 interface Distance {
@@ -61,9 +61,6 @@ export interface AlignmentModifierContexts {
 type addToContextFn<T> = (tickable: Tickable, context: T, voiceIndex: number) => void;
 type makeContextFn<T> = (tick?: { tickID: number }) => T;
 
-// Helper function
-const sumArray = (arr: number[]) => arr.reduce((a, b) => a + b, 0);
-
 /**
  * Create `Alignment`s for each tick in `voices`. Also calculate the
  * total number of ticks in voices.

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.
    */

src/util.ts

@@ -89,3 +89,10 @@ export function normalizeAngle(a: number): number {
   }
   return a;
 }
+
+/**
+ * Return the sum of an array of numbers.
+ */
+export function sumArray(arr: number[]): number {
+  return arr.reduce((a, b) => a + b, 0);
+}

src/voice.ts

@@ -9,7 +9,7 @@ import { Stave } from './stave';
 import { Tables } from './tables';
 import { Tickable } from './tickable';
 import { Category } from './typeguard';
-import { defined, RuntimeError } from './util';
+import { defined, RuntimeError, sumArray } from './util';
 
 export interface VoiceTime {
   num_beats: number;
@@ -88,6 +88,7 @@ export class Voice extends Element {
 
     // Recalculate total ticks.
     this.totalTicks = new Fraction(this.time.num_beats * (this.time.resolution / this.time.beat_value), 1);
+    // until tickables are added, the smallestTickCount is the same as the stated totalTicks duration.
     this.smallestTickCount = this.totalTicks.clone();
   }
 
@@ -116,14 +117,14 @@ export class Voice extends Element {
     return this.tickables;
   }
 
-  /** Get the voice mode. */
+  /** Get the voice mode (Voice.Mode.SOFT, STRICT, or FULL) */
   getMode(): number {
     return this.mode;
   }
 
   /**
    * Set the voice mode.
-   * @param mode value from `VoiceMode`
+   * @param mode value from `VoiceMode` or Voice.Mode
    */
   setMode(mode: number): this {
     this.mode = mode;
@@ -194,17 +195,21 @@ export class Voice extends Element {
    */
   setSoftmaxFactor(factor: number): this {
     this.options.softmaxFactor = factor;
+    this.expTicksUsed = 0; // reset
     return this;
   }
 
   /**
    * Calculate the sum of the exponents of all the ticks in this voice to use
-   * as the denominator of softmax.
+   * as the denominator of softmax.  (It is not the sum of the softmax(t) over all tickables)
+   *
+   * Note that the "exp" of "expTicksUsed" stands for "expontential" ticks used,
+   * not "expected" ticks used.
    */
   protected reCalculateExpTicksUsed(): number {
     const totalTicks = this.ticksUsed.value();
     const exp = (tickable: Tickable) => Math.pow(this.options.softmaxFactor, tickable.getTicks().value() / totalTicks);
-    this.expTicksUsed = this.tickables.map(exp).reduce((a, b) => a + b, 0);
+    this.expTicksUsed = sumArray(this.tickables.map(exp));
     return this.expTicksUsed;
   }