Documenting VexFlow objects

src/Common/Logging.ts

@@ -1,5 +1,10 @@
 /* tslint:disable:no-console */
 
+/**
+ * Class for logging messages, mainly for debugging purposes.
+ * It should be refactored soon, when an external logging framework
+ * will be chosen (probably log4js).
+ */
 export class Logging {
     public static debug(...args: any[]): void {
         console.debug("[OSMD] ", args.join(" "));

src/MusicalScore/Graphical/VexFlow/VexFlowConverter.ts

@@ -16,16 +16,33 @@ import {FontStyles} from "../../../Common/Enums/FontStyles";
 import {Fonts} from "../../../Common/Enums/Fonts";
 import {OutlineAndFillStyleEnum} from "../DrawingEnums";
 
+/**
+ * Helper class, which contains static methods which actually convert
+ * from OSMD objects to VexFlow objects.
+ */
 export class VexFlowConverter {
+    /**
+     * Mapping from numbers of alterations on the key signature to major keys
+     * @type {[alterationsNo: number]: string; }
+     */
     private static majorMap: {[_: number]: string; } = {
         "0": "C", 1: "G", 2: "D", 3: "A", 4: "E", 5: "B", 6: "F#", 7: "C#",
         8: "G#", "-1": "F", "-8": "Fb", "-7": "Cb", "-6": "Gb", "-5": "Db", "-4": "Ab", "-3": "Eb", "-2": "Bb",
     };
+    /**
+     * Mapping from numbers of alterations on the key signature to minor keys
+     * @type {[alterationsNo: number]: string; }
+     */
     private static minorMap: {[_: number]: string; } = {
         "1": "E", "7": "A#", "0": "A", "6": "D#", "3": "F#", "-5": "Bb", "-4": "F", "-7": "Ab", "-6": "Eb",
         "-1": "D", "4": "C#", "-3": "C", "-2": "G", "2": "B", "5": "G#", "-8": "Db", "8": "E#",
     };
 
+    /**
+     * Convert a fraction to a string which represents a duration in VexFlow
+     * @param fraction a fraction representing the duration of a note
+     * @returns {string}
+     */
     public static duration(fraction: Fraction): string {
         let dur: number = fraction.RealValue;
         if (dur >= 1) {
@@ -59,7 +76,7 @@ export class VexFlowConverter {
     }
 
     /**
-     * Converts AccidentalEnum to vexFlow accidental string
+     * Converts AccidentalEnum to a string which represents an accidental in VexFlow
      * @param accidental
      * @returns {string}
      */
@@ -86,7 +103,11 @@ export class VexFlowConverter {
         return acc;
     }
 
-
+    /**
+     * Convert a set of GraphicalNotes to a VexFlow StaveNote
+     * @param notes form a chord on the staff
+     * @returns {Vex.Flow.StaveNote}
+     */
     public static StaveNote(notes: GraphicalNote[]): Vex.Flow.StaveNote {
         let keys: string[] = [];
         let accidentals: string[] = [];
@@ -125,6 +146,12 @@ export class VexFlowConverter {
         return vfnote;
     }
 
+    /**
+     * Convert a ClefInstruction to a string representing a clef type in VexFlow
+     * @param clef
+     * @returns {string}
+     * @constructor
+     */
     public static Clef(clef: ClefInstruction): string {
         let type: string;
         switch (clef.ClefType) {
@@ -148,6 +175,12 @@ export class VexFlowConverter {
         return type;
     }
 
+    /**
+     * Convert a RhythmInstruction to a VexFlow TimeSignature object
+     * @param rhythm
+     * @returns {Vex.Flow.TimeSignature}
+     * @constructor
+     */
     public static TimeSignature(rhythm: RhythmInstruction): Vex.Flow.TimeSignature {
         let timeSpec: string;
         switch (rhythm.SymbolEnum) {
@@ -165,6 +198,11 @@ export class VexFlowConverter {
         return new Vex.Flow.TimeSignature(timeSpec);
     }
 
+    /**
+     * Convert a KeyInstruction to a string representing in VexFlow a key
+     * @param key
+     * @returns {string}
+     */
     public static keySignature(key: KeyInstruction): string {
         if (key === undefined) {
             return undefined;
@@ -185,7 +223,13 @@ export class VexFlowConverter {
         return ret;
     }
 
+    /**
+     * Converts a lineType to a VexFlow StaveConnector type
+     * @param lineType
+     * @returns {any}
+     */
     public static line(lineType: SystemLinesEnum): any {
+        // TODO Not all line types are correctly mapped!
         switch (lineType) {
             case SystemLinesEnum.SingleThin:
                 return Vex.Flow.StaveConnector.type.SINGLE;
@@ -205,6 +249,13 @@ export class VexFlowConverter {
         }
     }
 
+    /**
+     * Construct a string which can be used in a CSS font property
+     * @param fontSize
+     * @param fontStyle
+     * @param font
+     * @returns {string}
+     */
     public static font(fontSize: number, fontStyle: FontStyles = FontStyles.Regular, font: Fonts = Fonts.TimesNewRoman): string {
         let style: string = "normal";
         let weight: string = "normal";
@@ -239,8 +290,13 @@ export class VexFlowConverter {
         return  style + " " + weight + " " + Math.floor(fontSize) + "px " + family;
     }
 
+    /**
+     * Convert OutlineAndFillStyle to CSS properties
+     * @param styleId
+     * @returns {string}
+     */
     public static style(styleId: OutlineAndFillStyleEnum): string {
-        // TODO
+        // TODO To be implemented
         return "purple";
     }
 }

src/MusicalScore/Graphical/VexFlow/VexFlowGraphicalNote.ts

@@ -6,6 +6,9 @@ import {ClefInstruction} from "../../VoiceData/Instructions/ClefInstruction";
 import {VexFlowConverter} from "./VexFlowConverter";
 import {Pitch} from "../../../Common/DataObjects/Pitch";
 
+/**
+ * The VexFlow version of a [[GraphicalNote]].
+ */
 export class VexFlowGraphicalNote extends GraphicalNote {
     constructor(note: Note, parent: GraphicalStaffEntry, activeClef: ClefInstruction) {
         super(note, parent);
@@ -16,10 +19,18 @@ export class VexFlowGraphicalNote extends GraphicalNote {
         }
     }
 
+    // The pitch of this note as given by VexFlowConverter.pitch
     public vfpitch: [string, string, ClefInstruction];
+    // The corresponding VexFlow StaveNote (plus its index in the chord)
     private vfnote: [Vex.Flow.StaveNote, number];
+    // The current clef
     private clef: ClefInstruction;
 
+    /**
+     * Update the pitch of this note. Necessary in order to display correctly
+     * accidentals, this is called by VexFlowGraphicalSymbolFactory.addGraphicalAccidental.
+     * @param pitch
+     */
     public setPitch(pitch: Pitch): void {
         if (this.vfnote) {
             let acc: string = VexFlowConverter.accidental(pitch.Accidental);
@@ -33,14 +44,11 @@ export class VexFlowGraphicalNote extends GraphicalNote {
     }
 
     /**
-     * Set the corresponding VexFlow StaveNote together with its index
+     * Set the VexFlow StaveNote corresponding to this GraphicalNote, together with its index in the chord.
      * @param note
      * @param index
      */
     public setIndex(note: Vex.Flow.StaveNote, index: number): void {
         this.vfnote = [note, index];
-        //if (this.vfpitch && this.vfpitch[1]) {
-        //    note.addAccidental(index, new Vex.Flow.Accidental(this.vfpitch[1]));
-        //}
     }
 }

src/MusicalScore/Graphical/VexFlow/VexFlowMeasure.ts

@@ -291,6 +291,10 @@ export class VexFlowMeasure extends StaffMeasure {
         this.connectors.push(connector);
     }
 
+    /**
+     * Return the VexFlow Stave corresponding to this StaffMeasure
+     * @returns {Vex.Flow.Stave}
+     */
     public getVFStave(): Vex.Flow.Stave {
         return this.stave;
     }
@@ -313,8 +317,11 @@ export class VexFlowMeasure extends StaffMeasure {
     //
     //}
 
+    /**
+     * After re-running the formatting on the VexFlow Stave, update the
+     * space needed by Instructions (in VexFlow: StaveModifiers)
+     */
     private updateInstructionWidth(): void {
-        //this.stave.format();
         this.beginInstructionsWidth = (this.stave.getNoteStartX() - this.stave.getX()) / unitInPixels;
         this.endInstructionsWidth = (this.stave.getNoteEndX() - this.stave.getX()) / unitInPixels;
     }

src/MusicalScore/Graphical/VexFlow/VexFlowMusicSystem.ts

@@ -8,8 +8,6 @@ import {SystemLine} from "../SystemLine";
 import {VexFlowMeasure} from "./VexFlowMeasure";
 import {VexFlowConverter} from "./VexFlowConverter";
 
-//import Vex = require("vexflow");
-
 export class VexFlowMusicSystem extends MusicSystem {
     constructor(parent: GraphicalMusicPage, id: number) {
         super(parent, id);

src/MusicalScore/Graphical/VexFlow/VexFlowStaffEntry.ts

@@ -16,7 +16,7 @@ export class VexFlowStaffEntry extends GraphicalStaffEntry {
 
     /**
      *
-     * @returns {number} the x-position (in units) of this Staff Entry
+     * @returns {number} the x-position (in units) of this StaffEntry
      */
     public getX(): number {
         let x: number = 0;
@@ -28,6 +28,9 @@ export class VexFlowStaffEntry extends GraphicalStaffEntry {
                 n += 1;
             }
         }
+        if (n === 0) {
+            return 0;
+        }
         return x / n / unitInPixels;
     }
 }

src/MusicalScore/Graphical/VexFlow/VexFlowTextMeasurer.ts

@@ -11,8 +11,16 @@ export class VexFlowTextMeasurer implements ITextMeasurer {
         let canvas: HTMLCanvasElement = document.createElement("canvas");
         this.context = canvas.getContext("2d");
     }
+    // The context of a canvas used internally to compute font sizes
     private context: CanvasRenderingContext2D;
 
+    /**
+     *
+     * @param text
+     * @param font
+     * @param style
+     * @returns {number}
+     */
     public computeTextWidthToHeightRatio(text: string, font: Fonts, style: FontStyles): number {
         this.context.font = VexFlowConverter.font(20, style, font);
         return this.context.measureText(text).width / 20;