Merge pull request #1073 from rvilarl/api/easyscore

Api Documentation: easyscore

src/easyscore.ts

@@ -1,7 +1,5 @@
 // [VexFlow](http://vexflow.com) - Copyright (c) Mohit Muthanna 2010.
-//
-// This class implements a parser for a simple language to generate
-// VexFlow objects.
+// MIT License
 
 /* eslint max-classes-per-file: "off" */
 
@@ -15,7 +13,7 @@ import { RenderContext } from './types/common';
 import { Accidental } from './accidental';
 import { Modifier } from './modifier';
 import { Voice } from './voice';
-import { Note } from 'note';
+import { TupletOptions } from './tuplet';
 
 // To enable logging for this class. Set `Vex.Flow.EasyScore.DEBUG` to `true`.
 // eslint-disable-next-line
@@ -415,6 +413,10 @@ export interface EasyScoreDefaults {
   [x: string]: any; // allow arbitrary properties via set(defaults)
 }
 
+/**
+ * EasyScore implements a parser for a simple language to generate
+ * VexFlow objects.
+ */
 export class EasyScore {
   static DEBUG: boolean = false;
 
@@ -434,6 +436,12 @@ export class EasyScore {
     };
   }
 
+  /**
+   * Set the Score defaults (`Type` must be set appropriately to avoid Errors when adding Staves).
+   * @param defaults.clef default clef ( treble | bass ...) see {@link Clef.types}
+   * @param defaults.type default time signature ( 4/4 | 9/8 ...)
+   * @param defaults.stem default stem arrangement (auto | up | down)
+   */
   set(defaults: Partial<EasyScoreDefaults>): this {
     Object.assign(this.defaults, defaults);
     return this;
@@ -471,16 +479,12 @@ export class EasyScore {
     return result;
   }
 
-  // TODO: Add stricter typing after migrating Factory
-  // eslint-disable-next-line
-  beam(notes: StaveNote[], options: any = {}): StaveNote[] {
+  beam(notes: StaveNote[], options?: { autoStem?: boolean; secondaryBeamBreaks?: number[] }): StaveNote[] {
     this.factory.Beam({ notes, options });
     return notes;
   }
 
-  // TODO: Add stricter typing after migrating Factory
-  // eslint-disable-next-line
-  tuplet(notes: StaveNote[], options: any = {}): StaveNote[] {
+  tuplet(notes: StaveNote[], options?: TupletOptions): StaveNote[] {
     this.factory.Tuplet({ notes, options });
     return notes;
   }
@@ -491,9 +495,7 @@ export class EasyScore {
     return this.builder.getElements().notes;
   }
 
-  // TODO: Add stricter typing after migrating Factory
-  // eslint-disable-next-line
-  voice(notes: Note[], options?: any): Voice {
+  voice(notes: StaveNote[], options: { time?: string; options?: { softmaxFactor: number } } = {}): Voice {
     options = { time: this.defaults.time, ...options };
     return this.factory.Voice(options).addTickables(notes);
   }

src/factory.ts

@@ -1,12 +1,6 @@
 // [VexFlow](http://vexflow.com) - Copyright (c) Mohit Muthanna 2010.
 // @author Mohit Cheppudira
-//
-// ## Description
-//
-// This file implements a high level API around VexFlow. It will eventually
-// become the canonical way to use VexFlow.
-//
-// *This API is currently DRAFT*
+// MIT License
 
 import { RuntimeError, log } from './util';
 import { Accidental } from './accidental';
@@ -74,13 +68,19 @@ export interface FactoryOptions {
   };
 }
 
-// To enable logging for this class. Set `Vex.Flow.Factory.DEBUG` to `true`.
 // eslint-disable-next-line
 function L(...args: any[]) {
   if (Factory.DEBUG) log('Vex.Flow.Factory', args);
 }
 
+/**
+ * Factory implements a high level API around VexFlow. It will eventually
+ * become the canonical way to use VexFlow.
+ *
+ * *This API is currently DRAFT*
+ */
 export class Factory {
+  /** To enable logging for this class. Set `Vex.Flow.Factory.DEBUG` to `true`. */
   static DEBUG: boolean;
 
   protected options: FactoryOptions;
@@ -92,6 +92,15 @@ export class Factory {
   protected renderQ!: Element[];
   protected systems!: System[];
 
+  /**
+   * Constructor.
+   *
+   * Example:
+   *
+   * Create an SVG renderer and attach it to the DIV element named "boo" to render using <page-width> 1200 and <page-height> 600
+   *
+   * `const vf: Factory = new Vex.Flow.Factory({renderer: { elementId: 'boo', width: 1200, height: 600 }});`
+   */
   constructor(options: Partial<FactoryOptions> = {}) {
     L('New factory: ', options);
     const defaults: FactoryOptions = {
@@ -116,6 +125,15 @@ export class Factory {
     this.setOptions(options);
   }
 
+  /**
+   * Static simplified function to access constructor without providing FactoryOptions
+   *
+   * Example:
+   *
+   * Create an SVG renderer and attach it to the DIV element named "boo" to render using <page-width> 1200 and <page-height> 600
+   *
+   * `const vf: Factory = Vex.Flow.Factory.newFromElementId('boo', 1200, 600 );`
+   */
   static newFromElementId(elementId: string | null, width = 500, height = 200): Factory {
     return new Factory({ renderer: { elementId, width, height, backend: Renderer.Backends.SVG } });
   }
@@ -176,7 +194,7 @@ export class Factory {
     return this.voices;
   }
 
-  // Returns pixels from current stave spacing.
+  /** Return pixels from current stave spacing. */
   space(spacing: number): number {
     if (!this.options.stave) throw new RuntimeError('NoStave');
     return this.options.stave.space * spacing;
@@ -642,6 +660,19 @@ export class Factory {
     return system;
   }
 
+  /**
+   * Creates EasyScore. Normally the first step after constructing a factory.
+   *
+   * Example:
+   *
+   * `const vf: Factory = new Vex.Flow.Factory({renderer: { elementId: 'boo', width: 1200, height: 600 }});`
+   *
+   * `const score: EasyScore = vf.EasyScore();`
+   * @param params.factory not required
+   * @param params.builder instance of Builder
+   * @param params.commitHooks function to call after a note element is created
+   * @param params.throwOnError throw error in case of parsing error
+   */
   EasyScore(params: EasyScoreOptions = {}): EasyScore {
     params.factory = this;
     return new EasyScore(params);
@@ -684,6 +715,7 @@ export class Factory {
     return textFont;
   }
 
+  /** Render the score. */
   draw(): void {
     this.systems.forEach((i) => i.setContext(this.context).format());
     this.staves.forEach((i) => i.setContext(this.context).draw());

src/stave.ts

@@ -1,4 +1,5 @@
 // [VexFlow](http://vexflow.com) - Copyright (c) Mohit Muthanna 2010.
+// MIT License
 
 import { RuntimeError } from './util';
 import { Element, ElementStyle } from './element';
@@ -484,7 +485,7 @@ export class Stave extends Element {
     return this;
   }
 
-  setTimeSignature(timeSpec: string, customPadding: number, position?: number): this {
+  setTimeSignature(timeSpec: string, customPadding?: number, position?: number): this {
     if (position === undefined) {
       position = StaveModifier.Position.BEGIN;
     }
@@ -504,6 +505,16 @@ export class Stave extends Element {
     return this;
   }
 
+  /**
+   * Add a key signature to the stave.
+   *
+   * Example:
+   * `stave.addKeySignature('Db');`
+   * @param keySpec new key specification `[A-G][b|#]?`
+   * @param cancelKeySpec
+   * @param position
+   * @returns
+   */
   addKeySignature(keySpec: string, cancelKeySpec?: string, position?: number): this {
     if (position === undefined) {
       position = StaveModifier.Position.BEGIN;
@@ -512,6 +523,18 @@ export class Stave extends Element {
     return this;
   }
 
+  /**
+   * Add a clef to the stave.
+   *
+   * Example:
+   *
+   * stave.addClef('treble')
+   * @param clef clef (treble|bass|...) see {@link Clef.types}
+   * @param size
+   * @param annotation
+   * @param position
+   * @returns
+   */
   addClef(clef: string, size?: string, annotation?: string, position?: number): this {
     if (position === undefined || position === StaveModifier.Position.BEGIN) {
       this.clef = clef;
@@ -528,6 +551,17 @@ export class Stave extends Element {
     return this;
   }
 
+  /**
+   * Add a time signature to the stave
+   *
+   * Example:
+   *
+   * `stave.addTimeSignature('4/4');`
+   * @param timeSpec time signature specification `(C\||C|\d\/\d)`
+   * @param customPadding
+   * @param position
+   * @returns
+   */
   addTimeSignature(timeSpec: string, customPadding?: number, position?: number): this {
     this.addModifier(new TimeSignature(timeSpec, customPadding), position);
     return this;

src/system.ts

@@ -3,7 +3,7 @@
 
 import { Element } from './element';
 import { Factory } from './factory';
-import { Formatter, FormatterOptions } from './formatter';
+import { FormatOptions, Formatter, FormatterOptions } from './formatter';
 import { Note } from './note';
 import { Stave, StaveOptions } from './stave';
 import { StaveConnector } from './staveconnector';
@@ -27,9 +27,12 @@ export interface SystemParams {
 
 /**
  * Formatting for systems created/drawn from factory:
+ *
  * If width is provided, the system will use the specified width.
+ *
  * If noJustification flag is 'true', there is no justification between voices
  * Otherwise, autoWidth defaults to true.
+ *
  * If autowidth is true, the system uses format.preCalculateMinWidth
  * for the width of all voices, and default stave padding
  */
@@ -45,6 +48,7 @@ export interface SystemOptions {
   width: number;
   y: number;
   details: SystemFormatterOptions;
+  formatOptions: FormatOptions;
   noJustification: boolean;
 }
 
@@ -86,6 +90,9 @@ export class System extends Element {
         alpha: 0.5, // formatter tuner learning/shifting rate
         ...options.details,
       },
+      formatOptions: {
+        ...options.formatOptions,
+      },
     };
     if (this.options.noJustification === false && typeof options.width === 'undefined') {
       this.options.autoWidth = true;
@@ -114,7 +121,23 @@ export class System extends Element {
     return this.connector;
   }
 
-  /** Add stave to the system. */
+  /**
+   * Add stave to the system.
+   *
+   * Examples:
+   *
+   *  (one voice)
+   *
+   * `system.addStave({voices: [score.voice(score.notes('C#5/q, B4, A4, G#4'))]});`
+   *
+   *  (two voices)
+   *
+   * `system.addStave({voices: [`
+   *
+   *  `score.voice(score.notes('C#5/q, B4, A4, G#4', {stem: 'up'})),`
+   *
+   *  `score.voice(score.notes('C#4/h, C#4', {stem: 'down'}))]});`
+   */
   addStave(paramsItems: Partial<SystemParams>): Stave {
     let stave = paramsItems.stave;
     if (!stave) {
@@ -199,7 +222,7 @@ export class System extends Element {
         ? this.options.width - this.options.x
         : this.options.width - (startX - this.options.x) - Stave.defaultPadding;
     }
-    formatter.format(allVoices, this.options.noJustification ? 0 : justifyWidth);
+    formatter.format(allVoices, this.options.noJustification ? 0 : justifyWidth, this.options.formatOptions);
 
     for (let i = 0; i < this.options.formatIterations; i++) {
       formatter.tune({ alpha: this.options.details.alpha });