Documenting classes i

src/Common/DataObjects/Fraction.ts

@@ -1,12 +1,21 @@
-// FIXME: Check the operators' names
-// FIXME: This class should probably be immutable?
+// TODO: Check the operators' names
+// TODO: This class should probably be immutable?
 
+/**
+ * A class representing mathematical fractions, which have a numerator and a denominator.
+ */
 export class Fraction {
     private static maximumAllowedNumber: number = 46340;
     private numerator: number = 0;
     private denominator: number = 1;
     private realValue: number;
 
+    /**
+     * Returns the maximum of two fractions (does not clone)
+     * @param f1
+     * @param f2
+     * @returns {Fraction}
+     */
     public static max(f1: Fraction, f2: Fraction): Fraction {
         if (f1.RealValue > f2.RealValue) {
             return f1;
@@ -16,10 +25,14 @@ export class Fraction {
     }
 
     public static Equal(f1: Fraction, f2: Fraction): boolean {
-        // FIXME
         return f1.Denominator === f2.Denominator && f1.Numerator === f2.Numerator;
     }
 
+    /**
+     * The same as Fraction.clone
+     * @param fraction
+     * @returns {Fraction}
+     */
     public static createFromFraction(fraction: Fraction): Fraction {
         return new Fraction(fraction.numerator, fraction.denominator);
     }
@@ -56,6 +69,13 @@ export class Fraction {
         return a;
     }
 
+    /**
+     *
+     * @param numerator
+     * @param denominator
+     * @param simplify - If simplify is true, then the fraction is simplified
+     *      to make both the numerator and denominator coprime, and less than maximumAllowedNumber.
+     */
     constructor(numerator: number = 0, denominator: number = 1, simplify: boolean = true) {
         this.numerator = numerator;
         this.denominator = denominator;

src/Common/DataObjects/OSMDColor.ts

@@ -1,16 +1,23 @@
+/**
+ * Represents a color in RGBA
+ */
 export class OSMDColor {
     public alpha: number;
     public red: number;
     public green: number;
     public blue: number;
 
-    // FIXME:
     /*constructor(alpha: number, red: number, green: number, blue: number) {
         this.alpha = alpha;
         this.red = red;
         this.green = green;
         this.blue = blue;
     }*/
+
+    /*
+     * Color names are based on the definitions at https://msdn.microsoft.com/de-de/library/aa358802(vs.85).aspx
+     * ...but changed a bit by the famous Mc Overacre
+     */
     constructor(red: number, green: number, blue: number) {
         this.alpha = 255;
         this.red = red;
@@ -41,6 +48,7 @@ export class OSMDColor {
     public static get DarkBlue(): OSMDColor {
         return new OSMDColor(0, 0, 140);
     }
+
     // For debugging:
     public static get Debug1(): OSMDColor {
         return new OSMDColor(200, 0, 140);
@@ -53,7 +61,6 @@ export class OSMDColor {
     }
 
     public toString(): string {
-        // FIXME RGBA
-        return "rgb(" + this.red + "," + this.green + "," + this.blue + ")";
+        return "rgb(" + this.red + "," + this.green + "," + this.blue + "," + this.alpha + ")";
     }
 }

src/Common/DataObjects/Pitch.ts

@@ -1,3 +1,4 @@
+// The value of the enum indicates the number of halftoneSteps from one note to the next
 export enum NoteEnum {
     C = 0,
     D = 2,
@@ -16,6 +17,7 @@ export enum AccidentalEnum {
     DOUBLESHARP = 2
 }
 
+// This class represents a musical note. The middle A (440 Hz) lies in the octave with the value 1.
 export class Pitch {
     public static pitchEnumValues: NoteEnum[] = [
         NoteEnum.C, NoteEnum.D, NoteEnum.E, NoteEnum.F, NoteEnum.G, NoteEnum.A, NoteEnum.B,
@@ -181,6 +183,7 @@ export class Pitch {
         return this.halfTone;
     }
 
+    // This method returns a new Pitch transposed by the given factor
     public getTransposedPitch(factor: number): Pitch {
         if (factor > 12) {
             throw new Error("rewrite this method to handle bigger octave changes or don't use is with bigger octave changes!");
@@ -234,6 +237,7 @@ export class Pitch {
         return !(p1 === p2);
     }
 
+    // This method returns a new Pitch factor-Halftones higher than the current Pitch
     private getHigherPitchByTransposeFactor(factor: number): Pitch {
         let noteEnumIndex: number = Pitch.pitchEnumValues.indexOf(this.fundamentalNote);
         let newOctave: number = this.octave;

src/Common/DataObjects/PointF2D.ts

@@ -1,3 +1,4 @@
+// Represent a point on a plane, with (x,y) coordinates
 export class PointF2D {
     public x: number = 0;
     public y: number = 0;

src/Common/DataObjects/RectangleF2D.ts

@@ -1,12 +1,22 @@
 import {SizeF2D} from "./SizeF2D";
 import {PointF2D} from "./PointF2D";
 
+/**
+ * Represent a rectangle on a plane
+ */
 export class RectangleF2D {
     public x: number = 0;
     public y: number = 0;
     public width: number = 0;
     public height: number = 0;
 
+    /**
+     *
+     * @param x
+     * @param y
+     * @param width
+     * @param height
+     */
     constructor(x: number, y: number, width: number, height: number) {
         this.x = x;
         this.y = y;

src/Common/DataObjects/SizeF2D.ts

@@ -1,3 +1,6 @@
+/**
+ * Represent the size of a 2D object, with (width, height)
+ */
 export class SizeF2D {
     public width: number;
     public height: number;

src/Common/Enums/FontStyles.ts

@@ -1,3 +1,6 @@
+/**
+ * The styles available to write text on the music sheet
+ */
 export enum FontStyles {
     Regular = 0,
     Bold = 1,

src/Common/Enums/Fonts.ts

@@ -1,3 +1,6 @@
+/**
+ * The fonts available for writing on the sheet music
+ */
 export enum Fonts {
     TimesNewRoman,
     Kokila

src/Common/Enums/TextAlignment.ts

@@ -1,3 +1,7 @@
+/**
+ * The possible positioning of text on the sheet music
+ * (used for example with title, composer, author, etc.)
+ */
 export enum TextAlignment {
     LeftTop,
     LeftCenter,

src/Common/FileIO/Xml.ts

@@ -1,5 +1,12 @@
+/**
+ * IXmlAttribute is just Attr
+ */
 export type IXmlAttribute = Attr;
 
+/**
+ * Just a wrapper for an XML Element object.
+ * It facilitates handling of XML elements by OSMD
+ */
 export class IXmlElement {
     public name: string;
     public value: string;
@@ -10,6 +17,10 @@ export class IXmlElement {
     private attrs: IXmlAttribute[];
     private elem: Element;
 
+    /**
+     * Wraps 'elem' Element in a IXmlElement
+     * @param elem
+     */
     constructor(elem: Element) {
         if (elem === undefined) {
             throw new Error("IXmlElement: expected Element, got undefined");
@@ -30,10 +41,19 @@ export class IXmlElement {
         }
     }
 
+    /**
+     * Get the attribute with the given name
+     * @param attributeName
+     * @returns {Attr}
+     */
     public attribute(attributeName: string): IXmlAttribute {
         return this.elem.attributes.getNamedItem(attributeName);
     }
 
+    /**
+     * Get all attributes
+     * @returns {IXmlAttribute[]}
+     */
     public attributes(): IXmlAttribute[] {
         if (!this.attrs) {
             let attributes: NamedNodeMap = this.elem.attributes;
@@ -46,6 +66,11 @@ export class IXmlElement {
         return this.attrs;
     }
 
+    /**
+     * Get the first child element with the given node name
+     * @param elementName
+     * @returns {IXmlElement}
+     */
     public element(elementName: string): IXmlElement {
         let nodes: NodeList = this.elem.childNodes;
         for (let i: number = 0, length: number = nodes.length; i < length; i += 1) {
@@ -56,6 +81,11 @@ export class IXmlElement {
         }
     }
 
+    /**
+     * Get the children with the given node name (if given, otherwise all child elements)
+     * @param nodeName
+     * @returns {IXmlElement[]}
+     */
     public elements(nodeName?: string): IXmlElement[] {
         let nodes: NodeList = this.elem.childNodes;
         let ret: IXmlElement[] = [];

src/MusicalScore/Graphical/AccidentalCalculator.ts

@@ -29,6 +29,9 @@ export class AccidentalCalculator {
         this.reactOnKeyInstructionChange();
     }
 
+    /**
+     * This method is called after each Measure
+     */
     public doCalculationsAtEndOfMeasure(): void {
         this.currentInMeasureNoteAlterationsDict.clear();
         for (let key of this.keySignatureNoteAlterationsDict.keys()) {

src/MusicalScore/Graphical/BoundingBox.ts

@@ -204,6 +204,9 @@ export class BoundingBox {
         }
     }
 
+    /**
+     * This method calculates the Absolute Positions recursively
+     */
     public calculateAbsolutePositionsRecursiveWithoutTopelement(): void {
         this.absolutePosition.x = 0.0;
         this.absolutePosition.y = 0.0;
@@ -213,6 +216,11 @@ export class BoundingBox {
         }
     }
 
+    /**
+     * This method calculates the Absolute Positions recursively
+     * @param x
+     * @param y
+     */
     public calculateAbsolutePositionsRecursive(x: number, y: number): void {
         this.absolutePosition.x = this.relativePosition.x + x;
         this.absolutePosition.y = this.relativePosition.y + y;
@@ -222,6 +230,9 @@ export class BoundingBox {
         }
     }
 
+    /**
+     * This method calculates the BoundingBoxes
+     */
     public calculateBoundingBox(): void {
         if (this.childElements.length === 0) {
             return;
@@ -230,6 +241,8 @@ export class BoundingBox {
             let childElement: BoundingBox = this.ChildElements[idx];
             childElement.calculateBoundingBox();
         }
+
+        // initialize with max/min values
         let minLeft: number = Number.MAX_VALUE;
         let maxRight: number = Number.MIN_VALUE;
         let minTop: number = Number.MAX_VALUE;
@@ -238,6 +251,8 @@ export class BoundingBox {
         let maxMarginRight: number = Number.MIN_VALUE;
         let minMarginTop: number = Number.MAX_VALUE;
         let maxMarginBottom: number = Number.MIN_VALUE;
+
+        // apart from symbol elements, where we initialize with the symbol's borders
         if (this.isSymbol) {
             minLeft = this.borderLeft;
             maxRight = this.borderRight;
@@ -248,6 +263,8 @@ export class BoundingBox {
             minMarginTop = this.borderMarginTop;
             maxMarginBottom = this.borderMarginBottom;
         }
+
+        // ChildElements will have their borders calculated, so calculate current borders
         for (let idx: number = 0, len: number = this.ChildElements.length; idx < len; ++idx) {
             let childElement: BoundingBox = this.ChildElements[idx];
             minLeft = Math.min(minLeft, childElement.relativePosition.x + childElement.borderLeft);
@@ -259,6 +276,8 @@ export class BoundingBox {
             minMarginTop = Math.min(minMarginTop, childElement.relativePosition.y + childElement.borderMarginTop);
             maxMarginBottom = Math.max(maxMarginBottom, childElement.relativePosition.y + childElement.borderMarginBottom);
         }
+
+        // ChildElements will have their borders calculated, so calculate current borders
         this.borderLeft = minLeft;
         this.borderRight = maxRight;
         this.borderTop = minTop;
@@ -306,6 +325,12 @@ export class BoundingBox {
         this.calculateMarginRectangle();
     }
 
+    /**
+     * This method computes the first non-overlapping position in the placementPsi Element for the current (this) positionAndShapeInfo
+     * @param placementPsi
+     * @param direction
+     * @param position
+     */
     public computeNonOverlappingPositionWithMargin(placementPsi: BoundingBox, direction: ColDirEnum, position: PointF2D): void {
         this.RelativePosition = new PointF2D(position.x, position.y);
         this.setAbsolutePositionFromParent();
@@ -332,6 +357,11 @@ export class BoundingBox {
         while (hasBeenMoved);
     }
 
+    /**
+     * This method detects a collision (without margins)
+     * @param psi
+     * @returns {boolean}
+     */
     public collisionDetection(psi: BoundingBox): boolean {
         let overlapWidth: number = Math.min(this.AbsolutePosition.x + this.borderRight, psi.absolutePosition.x + psi.borderRight)
             - Math.max(this.AbsolutePosition.x + this.borderLeft, psi.absolutePosition.x + psi.borderLeft);
@@ -343,6 +373,11 @@ export class BoundingBox {
         return false;
     }
 
+    /**
+     * This method checks if the given Psi's Margins lie inside the current Psi's Margins.
+     * @param psi
+     * @returns {boolean}
+     */
     public liesInsideBorders(psi: BoundingBox): boolean {
         let leftBorderInside: boolean = (this.AbsolutePosition.x + this.borderLeft) <= (psi.absolutePosition.x + psi.borderLeft)
             && (psi.absolutePosition.x + psi.borderLeft) <= (this.AbsolutePosition.x + this.borderRight);
@@ -371,6 +406,11 @@ export class BoundingBox {
         return false;
     }
 
+    /**
+     * This method detects a collision (margin-wide)
+     * @param psi
+     * @returns {boolean}
+     */
     public marginCollisionDetection(psi: BoundingBox): boolean {
         let overlapWidth: number = Math.min(this.AbsolutePosition.x + this.borderMarginRight, psi.absolutePosition.x + psi.borderMarginRight)
             - Math.max(this.AbsolutePosition.x + this.borderMarginLeft, psi.absolutePosition.x + psi.borderMarginLeft);
@@ -382,6 +422,11 @@ export class BoundingBox {
         return false;
     }
 
+    /**
+     * This method checks if the given Psi's Margins lie inside the current Psi's Margins
+     * @param psi
+     * @returns {boolean}
+     */
     public liesInsideMargins(psi: BoundingBox): boolean {
         let leftMarginInside: boolean = (this.AbsolutePosition.x + this.borderMarginLeft) <= (psi.absolutePosition.x + psi.borderMarginLeft)
             && (psi.absolutePosition.x + psi.borderMarginLeft) <= (this.AbsolutePosition.x + this.borderMarginRight);
@@ -412,6 +457,12 @@ export class BoundingBox {
         return false;
     }
 
+    /**
+     * This method computes the first non-overlapping position in the placementPsi Element for the current (this) positionAndShapeInfo
+     * @param placementPsi
+     * @param direction
+     * @param position
+     */
     public computeNonOverlappingPosition(placementPsi: BoundingBox, direction: ColDirEnum, position: PointF2D): void {
         this.RelativePosition = new PointF2D(position.x, position.y);
         this.setAbsolutePositionFromParent();
@@ -434,8 +485,7 @@ export class BoundingBox {
                 default:
                     throw new ArgumentOutOfRangeException("direction");
             }
-        }
-        while (hasBeenMoved);
+        } while (hasBeenMoved); // as long as the element is moved
     }
 
     public getClickedObjectOfType<T>(clickPosition: PointF2D): T {
@@ -486,10 +536,22 @@ export class BoundingBox {
         this.boundingMarginRectangle = RectangleF2D.createFromLocationAndSize(this.upperLeftMarginCorner, this.marginSize);
     }
 
+    /**
+     * This method calculates the margin border along the given direction so that no collision takes place along this direction
+     * @param toBePlaced
+     * @param direction
+     */
     private calculateMarginPositionAlongDirection(toBePlaced: BoundingBox, direction: ColDirEnum): void {
+        // now this will be the "known" Element, about to get bigger with the toBePlaced
+        // eg toBePlaced will always be in the PositionAndShape hierarchy a Child of this
+        // example: this = StaffEntry, toBePlaced = Accidental
+
+        // logical return
         if (this === toBePlaced) {
             return;
         }
+
+        // check for collision only at symbols and return border
         if (this.isSymbol && this.marginCollisionDetection(toBePlaced)) {
             let shiftDistance: number = 0;
             switch (direction) {
@@ -517,16 +579,30 @@ export class BoundingBox {
                     throw new ArgumentOutOfRangeException("direction");
             }
         }
+
+        // perform check for all children iteratively and return border from children symbols
         for (let idx: number = 0, len: number = this.ChildElements.length; idx < len; ++idx) {
             let childElement: BoundingBox = this.ChildElements[idx];
             childElement.calculateMarginPositionAlongDirection(toBePlaced, direction);
         }
     }
 
+    /**
+     * This method calculates the border along the given direction so that no collision takes place along this direction
+     * @param toBePlaced
+     * @param direction
+     */
     private calculatePositionAlongDirection(toBePlaced: BoundingBox, direction: ColDirEnum): void {
+        // now this will be the "known" Element, about to get bigger with the toBePlaced
+        // eg toBePlaced will always be in the PositionAndShape hierarchy a Child of this
+        // example: this = StaffEntry, toBePlaced = Accidental
+
+        // logical return
         if (this === toBePlaced) {
             return;
         }
+
+        // check for collision only at symbols and return border
         if (this.isSymbol && this.collisionDetection(toBePlaced)) {
             let shiftDistance: number;
             switch (direction) {
@@ -554,6 +630,8 @@ export class BoundingBox {
                     throw new ArgumentOutOfRangeException("direction");
             }
         }
+
+        // perform check for all children iteratively and return border from children symbols
         for (let idx: number = 0, len: number = this.ChildElements.length; idx < len; ++idx) {
             let childElement: BoundingBox = this.ChildElements[idx];
             childElement.calculatePositionAlongDirection(toBePlaced, direction);