Documenting classes iv

src/MusicalScore/Graphical/MusicSheetCalculator.ts

@@ -396,6 +396,8 @@ export abstract class MusicSheetCalculator {
         if (allMeasures === undefined) {
             return;
         }
+
+        // visible 2D-MeasureList
         let visibleMeasureList: StaffMeasure[][] = [];
         for (let idx: number = 0, len: number = allMeasures.length; idx < len; ++idx) {
             let staffMeasures: StaffMeasure[] = allMeasures[idx];
@@ -409,7 +411,9 @@ export abstract class MusicSheetCalculator {
             visibleMeasureList.push(visibleStaffMeasures);
         }
 
+        // find out how many StaffLine Instances we need
         let numberOfStaffLines: number = 0;
+
         for (let idx: number = 0, len: number = visibleMeasureList.length; idx < len; ++idx) {
             let gmlist: StaffMeasure[] = visibleMeasureList[idx];
             numberOfStaffLines = Math.max(gmlist.length, numberOfStaffLines);
@@ -418,18 +422,30 @@ export abstract class MusicSheetCalculator {
         if (numberOfStaffLines === 0) {
             return;
         }
+
+        // build the MusicSystems
         let musicSystemBuilder: MusicSystemBuilder = new MusicSystemBuilder();
         musicSystemBuilder.initialize(this.graphicalMusicSheet, visibleMeasureList, numberOfStaffLines, this.symbolFactory);
         musicSystemBuilder.buildMusicSystems();
+
+        // check for Measures with only WholeRestNotes and correct their X-Position (middle of Measure)
         this.checkMeasuresForWholeRestNotes();
         if (!this.leadSheet) {
+            // calculate Beam Placement
             this.calculateBeams();
+            // possible Displacement of RestNotes
             this.optimizeRestPlacement();
+            // possible Displacement of RestNotes
             this.calculateStaffEntryArticulationMarks();
+            // calculate Ties
             this.calculateTieCurves();
         }
+        // calculate Sky- and BottomLine
+        // will have reasonable values only between ObjectsBorders (eg StaffEntries)
         this.calculateSkyBottomLines();
+        // calculate TupletsNumbers
         this.calculateTupletNumbers();
+        // calculate MeasureNumbers
         for (let idx: number = 0, len: number = this.graphicalMusicSheet.MusicPages.length; idx < len; ++idx) {
             let graphicalMusicPage: GraphicalMusicPage = this.graphicalMusicSheet.MusicPages[idx];
             for (let idx2: number = 0, len2: number = graphicalMusicPage.MusicSystems.length; idx2 < len2; ++idx2) {
@@ -437,26 +453,42 @@ export abstract class MusicSheetCalculator {
                 this.calculateMeasureNumberPlacement(musicSystem);
             }
         }
+        // calculate Slurs
         if (!this.leadSheet) {
             this.calculateSlurs();
         }
+        // calculate StaffEntry Ornaments
+        // (must come after Slurs)
         if (!this.leadSheet) {
             this.calculateOrnaments();
         }
+        // update Sky- and BottomLine with borderValues 0.0 and 4.0 respectively
+        // (must also come after Slurs)
         this.updateSkyBottomLines();
+        // calculate StaffEntry ChordSymbols
         this.calculateChordSymbols();
         if (!this.leadSheet) {
+            // calculate all Instantanious/Continuous Dynamics Expressions
             this.calculateDynamicExpressions();
+            // place neighbouring DynamicExpressions at the same height
             this.optimizeStaffLineDynamicExpressionsPositions();
+            // calculate all Mood and Unknown Expression
             this.calculateMoodAndUnknownExpressions();
+            // calculate all OctaveShifts
             this.calculateOctaveShifts();
+            // calucalte RepetitionInstructions (Dal Segno, Coda, etc)
             this.calculateWordRepetitionInstructions();
         }
+        // calculate endings last, so they appear above measure numbers
         this.calculateRepetitionEndings();
+        // calcualte all Tempo Expressions
         if (!this.leadSheet) {
             this.calculateTempoExpressions();
         }
+        // calculate all LyricWords Positions
         this.calculateLyricsPosition();
+        // update all StaffLine's Borders
+        // create temporary Object, just to call the methods (in order to avoid declaring them static)
         for (let idx: number = 0, len: number = this.graphicalMusicSheet.MusicPages.length; idx < len; ++idx) {
             let graphicalMusicPage: GraphicalMusicPage = this.graphicalMusicSheet.MusicPages[idx];
             for (let idx2: number = 0, len2: number = graphicalMusicPage.MusicSystems.length; idx2 < len2; ++idx2) {
@@ -467,9 +499,16 @@ export abstract class MusicSheetCalculator {
                 }
             }
         }
+        // calculate Comments for each Staffline
         this.calculateComments();
+        // Y-spacing
         this.calculateSystemYLayout();
+        // calculate marked Areas for Systems
         this.calculateMarkedAreas();
+
+        // the following must be done after Y-spacing, when the MusicSystems's final Dimensions are set
+        // set the final yPositions of Objects such as SystemLabels and SystemLinesContainers,
+        // create all System Lines, Brackets and MeasureNumbers (for all systems and for all pages)
         for (let idx: number = 0, len: number = this.graphicalMusicSheet.MusicPages.length; idx < len; ++idx) {
             let graphicalMusicPage: GraphicalMusicPage = this.graphicalMusicSheet.MusicPages[idx];
             for (let idx2: number = 0, len2: number = graphicalMusicPage.MusicSystems.length; idx2 < len2; ++idx2) {
@@ -501,9 +540,11 @@ export abstract class MusicSheetCalculator {
                     staffLine.addActivitySymbolClickArea();
                 }
             }
+            // calculate all Labels's Positions for the first Page
             if (graphicalMusicPage === this.graphicalMusicSheet.MusicPages[0]) {
                 this.calculatePageLabels(graphicalMusicPage);
             }
+            // calculate TopBottom Borders for all elements recursively
             graphicalMusicPage.PositionAndShape.calculateTopBottomBorders();
         }
     }
@@ -528,6 +569,9 @@ export abstract class MusicSheetCalculator {
         return;
     }
 
+    /**
+     * Iterate through all the [[StaffLine]]s in order to check for possible optimizations in the placement of the [[GraphicalExpression]]s.
+     */
     protected optimizeStaffLineDynamicExpressionsPositions(): void {
         return;
     }
@@ -536,6 +580,12 @@ export abstract class MusicSheetCalculator {
         return;
     }
 
+    /**
+     * Do layout on staff measures with only consist of a full rest.
+     * @param rest
+     * @param gse
+     * @param measure
+     */
     protected layoutMeasureWithWholeRest(rest: GraphicalNote, gse: GraphicalStaffEntry,
                                          measure: StaffMeasure): void {
         return;
@@ -578,6 +628,15 @@ export abstract class MusicSheetCalculator {
         return;
     }
 
+    /**
+     * Calculate a single GraphicalRepetition.
+     * @param start
+     * @param end
+     * @param numberText
+     * @param offset
+     * @param leftOpen
+     * @param rightOpen
+     */
     protected layoutSingleRepetitionEnding(start: StaffMeasure, end: StaffMeasure, numberText: string,
                                            offset: number, leftOpen: boolean, rightOpen: boolean): void {
         return;

src/MusicalScore/Graphical/MusicSheetDrawer.ts

@@ -26,7 +26,15 @@ import {GraphicalOctaveShift} from "./GraphicalOctaveShift";
 import {GraphicalObject} from "./GraphicalObject";
 
 /**
- * Class used to draw a GraphicalMusicSheet (with the .drawSheet method)
+ * Draw a [[GraphicalMusicSheet]] (through the .drawSheet method)
+ * The drawing is implemented with a top-down approach, starting from a music sheet, going through pages, systems, staffs...
+ * ... and ending in notes, beams, accidentals and other symbols.
+ * It's worth to say, that this class just draws the symbols and graphical elements, using the positions that have been computed before.
+ * But in any case, some of these previous positioning algorithms need the sizes of the concrete symbols (NoteHeads, sharps, flats, keys...).
+ * Therefore, there are some static functions on the 'Bounding Boxes' section used to compute these symbol boxes at the
+ * beginning for the later use in positioning algorithms.
+ *
+ * This class also includes the resizing and positioning of the symbols due to user interaction like zooming or panning.
  */
 export abstract class MusicSheetDrawer {
     public drawingParameters: DrawingParameters = new DrawingParameters();
@@ -69,9 +77,11 @@ export abstract class MusicSheetDrawer {
                 }
             }
         }
+        // Draw the vertical ScrollIndicator
         if (this.drawingParameters.drawScrollIndicator) {
             this.drawScrollIndicator();
         }
+        // Draw all the pages
         for (let page of this.graphicalMusicSheet.MusicPages) {
             this.drawPage(page);
         }

src/MusicalScore/Graphical/MusicSystem.ts

@@ -22,7 +22,7 @@ import {SystemLinePosition} from "./SystemLinePosition";
 import {Staff} from "../VoiceData/Staff";
 
 /**
- * A MusicSystem contains the StaffLines for all instruments, until a line break
+ * A MusicSystem contains the [[StaffLine]]s for all instruments, until a line break
  */
 export abstract class MusicSystem extends GraphicalObject {
     public needsToBeRedrawn: boolean = true;
@@ -103,7 +103,7 @@ export abstract class MusicSystem extends GraphicalObject {
     }
 
     /**
-     * This method creates the left vertical Line connecting all staves of the MusicSystem.
+     * Create the left vertical Line connecting all staves of the [[MusicSystem]].
      * @param lineWidth
      * @param systemLabelsRightMargin
      */
@@ -130,7 +130,7 @@ export abstract class MusicSystem extends GraphicalObject {
     }
 
     /**
-     * This method creates the vertical Lines after the End of all StaffLine's Measures
+     * Create the vertical Lines after the End of all [[StaffLine]]'s Measures
      * @param xPosition
      * @param lineWidth
      * @param lineType
@@ -159,6 +159,10 @@ export abstract class MusicSystem extends GraphicalObject {
         }
     }
 
+    /**
+     * Set the y-Positions of all the system lines in the system and creates the graphical Lines and dots within.
+     * @param rules
+     */
     public setYPositionsToVerticalLineObjectsAndCreateLines(rules: EngravingRules): void {
         // empty
     }
@@ -196,6 +200,11 @@ export abstract class MusicSystem extends GraphicalObject {
         return Fraction.plus(m.AbsoluteTimestamp, m.Duration);
     }
 
+    /**
+     * Create an InstrumentBracket for each multiStave Instrument.
+     * @param instruments
+     * @param staffHeight
+     */
     public createInstrumentBrackets(instruments: Instrument[], staffHeight: number): void {
         for (let idx: number = 0, len: number = instruments.length; idx < len; ++idx) {
             let instrument: Instrument = instruments[idx];
@@ -225,6 +234,12 @@ export abstract class MusicSystem extends GraphicalObject {
         }
     }
 
+    /**
+     * Create a GroupBracket for an [[InstrumentalGroup]].
+     * @param instrumentGroups
+     * @param staffHeight
+     * @param recursionDepth
+     */
     public createGroupBrackets(instrumentGroups: InstrumentalGroup[], staffHeight: number, recursionDepth: number): void {
         for (let idx: number = 0, len: number = instrumentGroups.length; idx < len; ++idx) {
             let instrumentGroup: InstrumentalGroup = instrumentGroups[idx];
@@ -264,6 +279,12 @@ export abstract class MusicSystem extends GraphicalObject {
         }
     }
 
+    /**
+     * Create the Instrument's Labels (only for the first [[MusicSystem]] of the first MusicPage).
+     * @param instrumentLabelTextHeight
+     * @param systemLabelsRightMargin
+     * @param labelMarginBorderFactor
+     */
     public createMusicSystemLabel(instrumentLabelTextHeight: number, systemLabelsRightMargin: number, labelMarginBorderFactor: number): void {
         if (this.parent === this.parent.Parent.MusicPages[0] && this === this.parent.MusicSystems[0]) {
             let instruments: Instrument[] = this.parent.Parent.ParentMusicSheet.getVisibleInstruments();
@@ -275,8 +296,13 @@ export abstract class MusicSystem extends GraphicalObject {
                 graphicalLabel.setLabelPositionAndShapeBorders();
                 this.labels.setValue(graphicalLabel, instrument);
                 this.boundingBox.ChildElements.push(graphicalLabel.PositionAndShape);
+
+                // X-Position will be 0 (Label starts at the same PointF_2D with MusicSystem)
+                // Y-Position will be calculated after the y-Spacing
                 graphicalLabel.PositionAndShape.RelativePosition = new PointF2D(0.0, 0.0);
             }
+
+            // calculate maxLabelLength (needed for X-Spacing)
             this.maxLabelLength = 0.0;
             let labels: GraphicalLabel[] = this.labels.keys();
             for (let idx: number = 0, len: number = labels.length; idx < len; ++idx) {
@@ -289,6 +315,9 @@ export abstract class MusicSystem extends GraphicalObject {
         }
     }
 
+    /**
+     * Set the Y-Positions for the MusicSystem's Labels.
+     */
     public setMusicSystemLabelsYPosition(): void {
         if (this.parent === this.parent.Parent.MusicPages[0] && this === this.parent.MusicSystems[0]) {
             this.labels.forEach((key: GraphicalLabel, value: Instrument): void => {
@@ -314,6 +343,11 @@ export abstract class MusicSystem extends GraphicalObject {
         }
     }
 
+    /**
+     * Check if two "adjacent" StaffLines have BOTH a StaffEntry with a StaffEntryLink.
+     * This is needed for the y-spacing algorithm.
+     * @returns {boolean}
+     */
     public checkStaffEntriesForStaffEntryLink(): boolean {
         let first: boolean = false;
         let second: boolean = false;
@@ -370,10 +404,10 @@ export abstract class MusicSystem extends GraphicalObject {
         throw new Error("not implemented");
     }
 
-    /// <summary>
-    /// This method creates all the graphical lines and dots needed to render a system line (e.g. bold-thin-dots..).
-    /// </summary>
-    /// <param name="psSystemLine"></param>
+    /**
+     * Create all the graphical lines and dots needed to render a system line (e.g. bold-thin-dots..).
+     * @param systemLine
+     */
     protected createLinesForSystemLine(systemLine: SystemLine): void {
         //Empty
     }
@@ -419,6 +453,10 @@ export abstract class MusicSystem extends GraphicalObject {
         return undefined;
     }
 
+    /**
+     * Update the xPosition of the [[MusicSystem]]'s [[StaffLine]]'s due to [[Label]] positioning.
+     * @param systemLabelsRightMargin
+     */
     private updateMusicSystemStaffLineXPosition(systemLabelsRightMargin: number): void {
         for (let idx: number = 0, len: number = this.StaffLines.length; idx < len; ++idx) {
             let staffLine: StaffLine = this.StaffLines[idx];

src/MusicalScore/Graphical/MusicSystemBuilder.ts

@@ -31,6 +31,10 @@ export class MusicSystemBuilder {
     private numberOfVisibleStaffLines: number;
     private rules: EngravingRules;
     private measureListIndex: number;
+
+    /**
+     * Does the mapping from the currently visible staves to the global staff-list of the music sheet.
+     */
     private visibleStaffIndices: number[];
     private activeRhythm: RhythmInstruction[];
     private activeKeys: KeyInstruction[];
@@ -61,6 +65,8 @@ export class MusicSystemBuilder {
         let systemMaxWidth: number = this.getFullPageSystemWidth();
         this.measureListIndex = 0;
         this.currentSystemParams = new SystemBuildParameters();
+
+        // the first System - create also its Labels
         this.currentSystemParams.currentSystem = this.initMusicSystem();
         this.layoutSystemStaves();
         this.currentSystemParams.currentSystem.createMusicSystemLabel(
@@ -77,6 +83,7 @@ export class MusicSystemBuilder {
             }
         }
 
+        // go through measures and add to system until system gets too long -> finish system and start next system.
         while (this.measureListIndex < numberOfMeasures) {
             let staffMeasures: StaffMeasure[] = this.measureList[this.measureListIndex];
             for (let idx: number = 0, len: number = staffMeasures.length; idx < len; ++idx) {
@@ -88,6 +95,12 @@ export class MusicSystemBuilder {
             let isFirstSourceMeasure: boolean = sourceMeasure === this.graphicalMusicSheet.ParentMusicSheet.getFirstSourceMeasure();
             let currentMeasureBeginInstructionsWidth: number = this.rules.MeasureLeftMargin;
             let currentMeasureEndInstructionsWidth: number = 0;
+
+            // calculate the current Measure Width:
+            // The width of a measure is build up from
+            // 1. the begin instructions (clef, Key, Rhythm),
+            // 2. the staff entries (= notes) and
+            // 3. the end instructions (actually only clefs)
             let measureStartLine: SystemLinesEnum = this.getMeasureStartLine();
             currentMeasureBeginInstructionsWidth += this.getLineWidth(staffMeasures[0], measureStartLine, isSystemStartMeasure);
             if (!this.leadSheet) {
@@ -98,9 +111,13 @@ export class MusicSystemBuilder {
             for (let i: number = 0; i < this.numberOfVisibleStaffLines; i++) {
                 currentMeasureVarWidth = Math.max(currentMeasureVarWidth, staffMeasures[i].minimumStaffEntriesWidth);
             }
+
+            // take into account the LineWidth after each Measure
             let measureEndLine: SystemLinesEnum = this.getMeasureEndLine();
             currentMeasureEndInstructionsWidth += this.getLineWidth(staffMeasures[0], measureEndLine, isSystemStartMeasure);
             let nextMeasureBeginInstructionWidth: number = this.rules.MeasureLeftMargin;
+
+            // Check if there are key or rhythm change instructions within the next measure:
             if (this.measureListIndex + 1 < this.measureList.length) {
                 let nextStaffMeasures: StaffMeasure[] = this.measureList[this.measureListIndex + 1];
                 let nextSourceMeasure: SourceMeasure = nextStaffMeasures[0].parentSourceMeasure;
@@ -118,13 +135,22 @@ export class MusicSystemBuilder {
                 this.updateActiveClefs(sourceMeasure, staffMeasures);
                 this.measureListIndex++;
             } else {
+                // finalize current system and prepare a new one
                 this.finalizeCurrentAndCreateNewSystem(staffMeasures, previousMeasureEndsSystem);
+                // don't increase measure index to check this measure now again
             }
             previousMeasureEndsSystem = sourceMeasureEndsSystem;
         }
         this.finalizeCurrentAndCreateNewSystem(this.measureList[this.measureList.length - 1], true);
     }
 
+    /**
+     * Set the Width of the staff-Measures of one source measure.
+     * @param staffMeasures
+     * @param width
+     * @param beginInstrWidth
+     * @param endInstrWidth
+     */
     private setMeasureWidth(staffMeasures: StaffMeasure[], width: number, beginInstrWidth: number, endInstrWidth: number): void {
         for (let idx: number = 0, len: number = staffMeasures.length; idx < len; ++idx) {
             let measure: StaffMeasure = staffMeasures[idx];
@@ -138,6 +164,12 @@ export class MusicSystemBuilder {
         }
     }
 
+    /**
+     * When the actual source measure doesn't fit any more, this method finalizes the current system and
+     * opens up a new empty system, where the actual measure will be added in the next iteration.
+     * @param measures
+     * @param isPartEndingSystem
+     */
     private finalizeCurrentAndCreateNewSystem(measures: StaffMeasure[], isPartEndingSystem: boolean = false): void {
         this.adaptRepetitionLineWithIfNeeded();
         if (!isPartEndingSystem) {
@@ -164,6 +196,12 @@ export class MusicSystemBuilder {
         }
     }
 
+    /**
+     * If a line repetition is ending and a new line repetition is starting at the end of the system,
+     * the double repetition line has to be split into two: one at the currently ending system and
+     * one at the next system.
+     * (this should be refactored at some point to not use a combined end/start line but always separated lines)
+     */
     private adaptRepetitionLineWithIfNeeded(): void {
         let systemMeasures: MeasureBuildParameters[] = this.currentSystemParams.systemMeasures;
         if (systemMeasures.length >= 1) {
@@ -198,6 +236,11 @@ export class MusicSystemBuilder {
         this.currentSystemParams.systemMeasureIndex++;
     }
 
+    /**
+     * Create a new [[GraphicalMusicPage]]
+     * (for now only one long page is used per music sheet, as we scroll down and have no page flips)
+     * @returns {GraphicalMusicPage}
+     */
     private createMusicPage(): GraphicalMusicPage {
         let page: GraphicalMusicPage = new GraphicalMusicPage(this.graphicalMusicSheet);
         this.graphicalMusicSheet.MusicPages.push(page);
@@ -209,6 +252,10 @@ export class MusicSystemBuilder {
         return page;
     }
 
+    /**
+     * Initialize a new [[MusicSystem]].
+     * @returns {MusicSystem}
+     */
     private initMusicSystem(): MusicSystem {
         let musicSystem: MusicSystem = this.symbolFactory.createMusicSystem(this.currentMusicPage, this.globalSystemIndex++);
         this.currentMusicPage.MusicSystems.push(musicSystem);
@@ -217,6 +264,10 @@ export class MusicSystemBuilder {
         return musicSystem;
     }
 
+    /**
+     * Get the width the system should have for a given page width.
+     * @returns {number}
+     */
     private getFullPageSystemWidth(): number {
         return this.currentMusicPage.PositionAndShape.Size.width - this.rules.PageLeftMargin
             - this.rules.PageRightMargin - this.rules.SystemLeftMargin - this.rules.SystemRightMargin;
@@ -272,6 +323,12 @@ export class MusicSystemBuilder {
         boundingBox.BorderBottom = yOffsetSum;
     }
 
+    /**
+     * Calculate the [[StaffLine]](s) needed for a [[MusicSystem]].
+     * @param musicSystem
+     * @param relativeYPosition
+     * @param staff
+     */
     private addStaffLineToMusicSystem(musicSystem: MusicSystem, relativeYPosition: number, staff: Staff): void {
         if (musicSystem !== undefined) {
             let staffLine: StaffLine = this.symbolFactory.createStaffLine(musicSystem, staff);
@@ -309,6 +366,10 @@ export class MusicSystemBuilder {
         }
     }
 
+    /**
+     * Initialize the active Instructions from the first [[SourceMeasure]] of first [[SourceMusicPart]].
+     * @param measureList
+     */
     private initializeActiveInstructions(measureList: StaffMeasure[]): void {
         let firstSourceMeasure: SourceMeasure = this.graphicalMusicSheet.ParentMusicSheet.getFirstSourceMeasure();
         if (firstSourceMeasure !== undefined) {
@@ -339,6 +400,13 @@ export class MusicSystemBuilder {
         return keyInstruction;
     }
 
+    /**
+     * Calculate the width needed for Instructions (Key, Clef, Rhythm, Repetition) for the measure.
+     * @param measures
+     * @param isSystemFirstMeasure
+     * @param isFirstSourceMeasure
+     * @returns {number}
+     */
     private addBeginInstructions(measures: StaffMeasure[], isSystemFirstMeasure: boolean, isFirstSourceMeasure: boolean): number {
         let measureCount: number = measures.length;
         if (measureCount === 0) {
@@ -360,6 +428,11 @@ export class MusicSystemBuilder {
         return totalBeginInstructionLengthX;
     }
 
+    /**
+     * Calculates the width needed for Instructions (Clef, Repetition) for the measure.
+     * @param measures
+     * @returns {number}
+     */
     private addEndInstructions(measures: StaffMeasure[]): number {
         let measureCount: number = measures.length;
         if (measureCount === 0) {
@@ -448,6 +521,13 @@ export class MusicSystemBuilder {
         return this.rules.MeasureRightMargin + measure.endInstructionsWidth;
     }
 
+    /**
+     * Track down and update the active ClefInstruction in Measure's StaffEntries.
+     * This has to be done after the measure is added to a system
+     * (otherwise already the check if the measure fits to the system would update the active clefs..)
+     * @param measure
+     * @param staffMeasures
+     */
     private updateActiveClefs(measure: SourceMeasure, staffMeasures: StaffMeasure[]): void {
         for (let visStaffIdx: number = 0, len: number = staffMeasures.length; visStaffIdx < len; visStaffIdx++) {
             let staffIndex: number = this.visibleStaffIndices[visStaffIdx];
@@ -489,6 +569,10 @@ export class MusicSystemBuilder {
         }
     }
 
+    /**
+     * Check if an extra Instruction [[Measure]] is needed.
+     * @param measures
+     */
     private checkAndCreateExtraInstructionMeasure(measures: StaffMeasure[]): void {
         let firstStaffEntries: SourceStaffEntry[] = measures[0].parentSourceMeasure.FirstInstructionsStaffEntries;
         let visibleInstructionEntries: SourceStaffEntry[] = [];
@@ -551,6 +635,10 @@ export class MusicSystemBuilder {
         return width;
     }
 
+    /**
+     * Add all current vertical Measures to currentSystem.
+     * @param staffMeasures
+     */
     private addStaveMeasuresToSystem(staffMeasures: StaffMeasure[]): void {
         if (staffMeasures[0] !== undefined) {
             let gmeasures: StaffMeasure[] = [];
@@ -568,6 +656,10 @@ export class MusicSystemBuilder {
         }
     }
 
+    /**
+     * Return the width of the corresponding [[SystemLine]] and set the corresponding [[SystemLineEnum]].
+     * @returns {SystemLinesEnum}
+     */
     private getMeasureStartLine(): SystemLinesEnum {
         let thisMeasureBeginsLineRep: boolean = this.thisMeasureBeginsLineRepetition();
         if (thisMeasureBeginsLineRep) {
@@ -599,6 +691,13 @@ export class MusicSystemBuilder {
         return SystemLinesEnum.SingleThin;
     }
 
+    /**
+     * Return the width of the corresponding [[SystemLine]] and sets the corresponding [[SystemLineEnum]].
+     * @param measure
+     * @param systemLineEnum
+     * @param isSystemStartMeasure
+     * @returns {number}
+     */
     private getLineWidth(measure: StaffMeasure, systemLineEnum: SystemLinesEnum, isSystemStartMeasure: boolean): number {
         let width: number = measure.getLineWidth(systemLineEnum);
         if (systemLineEnum === SystemLinesEnum.DotsBoldBoldDots) {
@@ -623,6 +722,10 @@ export class MusicSystemBuilder {
         return false;
     }
 
+    /**
+     * Check if at this [[Measure]] starts a [[Repetition]].
+     * @returns {boolean}
+     */
     private thisMeasureBeginsLineRepetition(): boolean {
         for (let idx: number = 0, len: number = this.measureList[this.measureListIndex].length; idx < len; ++idx) {
             let measure: StaffMeasure = this.measureList[this.measureListIndex][idx];
@@ -633,6 +736,10 @@ export class MusicSystemBuilder {
         return false;
     }
 
+    /**
+     * Check if a [[Repetition]] starts at the next [[Measure]].
+     * @returns {boolean}
+     */
     private nextMeasureBeginsLineRepetition(): boolean {
         let nextMeasureIndex: number = this.measureListIndex + 1;
         if (nextMeasureIndex >= this.graphicalMusicSheet.ParentMusicSheet.SourceMeasures.length) {
@@ -647,6 +754,10 @@ export class MusicSystemBuilder {
         return false;
     }
 
+    /**
+     * Check if this [[Measure]] is a [[Repetition]] ending.
+     * @returns {boolean}
+     */
     private thisMeasureEndsLineRepetition(): boolean {
         for (let idx: number = 0, len: number = this.measureList[this.measureListIndex].length; idx < len; ++idx) {
             let measure: StaffMeasure = this.measureList[this.measureListIndex][idx];
@@ -657,6 +768,10 @@ export class MusicSystemBuilder {
         return false;
     }
 
+    /**
+     * Check if a [[Repetition]] starts at the next [[Measure]].
+     * @returns {boolean}
+     */
     private nextMeasureBeginsWordRepetition(): boolean {
         let nextMeasureIndex: number = this.measureListIndex + 1;
         if (nextMeasureIndex >= this.graphicalMusicSheet.ParentMusicSheet.SourceMeasures.length) {
@@ -671,6 +786,10 @@ export class MusicSystemBuilder {
         return false;
     }
 
+    /**
+     * Check if this [[Measure]] is a [[Repetition]] ending.
+     * @returns {boolean}
+     */
     private thisMeasureEndsWordRepetition(): boolean {
         for (let idx: number = 0, len: number = this.measureList[this.measureListIndex].length; idx < len; ++idx) {
             let measure: StaffMeasure = this.measureList[this.measureListIndex][idx];
@@ -681,6 +800,10 @@ export class MusicSystemBuilder {
         return false;
     }
 
+    /**
+     * Check if the next [[Measure]] has a [[KeyInstruction]] change.
+     * @returns {boolean}
+     */
     private nextMeasureHasKeyInstructionChange(): boolean {
         return this.getNextMeasureKeyInstruction() !== undefined;
     }
@@ -698,6 +821,12 @@ export class MusicSystemBuilder {
         return undefined;
     }
 
+    /**
+     * Calculate the X ScalingFactor in order to strech the whole System.
+     * @param systemFixWidth
+     * @param systemVarWidth
+     * @returns {number}
+     */
     private calculateXScalingFactor(systemFixWidth: number, systemVarWidth: number): number {
         if (Math.abs(systemVarWidth - 0) < 0.00001 || Math.abs(systemFixWidth - 0) < 0.00001) {
             return 1.0;
@@ -709,6 +838,10 @@ export class MusicSystemBuilder {
         return scalingFactor;
     }
 
+    /**
+     * Stretch the whole System so that no white space is left at the end.
+     * @param isPartEndingSystem
+     */
     private stretchMusicSystem(isPartEndingSystem: boolean): void {
         let scalingFactor: number = this.calculateXScalingFactor(
             this.currentSystemParams.currentSystemFixWidth, this.currentSystemParams.currentSystemVarWidth
@@ -763,6 +896,10 @@ export class MusicSystemBuilder {
         }
     }
 
+    /**
+     * If the last [[MusicSystem]] doesn't need stretching, then this method decreases the System's Width,
+     * the [[StaffLine]]'s Width and the 5 [[StaffLine]]s length.
+     */
     private decreaseMusicSystemBorders(): void {
         let currentSystem: MusicSystem = this.currentSystemParams.currentSystem;
         let bb: BoundingBox = CollectionUtil.last(currentSystem.StaffLines[0].Measures).PositionAndShape;

src/MusicalScore/Graphical/OctaveShiftParams.ts

@@ -2,12 +2,15 @@ import {Fraction} from "../../Common/DataObjects/Fraction";
 import {OctaveShift} from "../VoiceData/Expressions/ContinuousExpressions/OctaveShift";
 
 export class OctaveShiftParams {
+
     constructor(openOctaveShift: OctaveShift, absoluteStartTimestamp: Fraction, absoluteEndTimestamp: Fraction) {
         this.getOpenOctaveShift = openOctaveShift;
         this.getAbsoluteStartTimestamp = absoluteStartTimestamp;
         this.getAbsoluteEndTimestamp = absoluteEndTimestamp;
     }
+
     public getOpenOctaveShift: OctaveShift;
     public getAbsoluteStartTimestamp: Fraction;
     public getAbsoluteEndTimestamp: Fraction;
+
 }

src/MusicalScore/Graphical/SelectionEndSymbol.ts

@@ -8,6 +8,7 @@ import {GraphicalLine} from "./GraphicalLine";
 import {CollectionUtil} from "../../Util/CollectionUtil";
 
 export class SelectionEndSymbol extends GraphicalObject {
+
     constructor(system: MusicSystem, xPosition: number) {
         super();
         let xCoordinate: number = xPosition;

src/MusicalScore/Graphical/SelectionStartSymbol.ts

@@ -8,6 +8,7 @@ import {BoundingBox} from "./BoundingBox";
 import {CollectionUtil} from "../../Util/CollectionUtil";
 
 export class SelectionStartSymbol extends GraphicalObject {
+
     constructor(system: MusicSystem, xPosition: number) {
         super();
         let xCoordinate: number = xPosition;

src/MusicalScore/Graphical/StaffLine.ts

@@ -10,7 +10,7 @@ import {StaffLineActivitySymbol} from "./StaffLineActivitySymbol";
 import {PointF2D} from "../../Common/DataObjects/PointF2D";
 
 /**
- * A StaffLine contains the measures in one line of the music sheet
+ * A StaffLine contains the [[Measure]]s in one line of the music sheet
  * (one instrument, one line, until a line break)
  */
 export abstract class StaffLine extends GraphicalObject {
@@ -84,6 +84,10 @@ export abstract class StaffLine extends GraphicalObject {
         this.parentMusicSystem.PositionAndShape.ChildElements.push(activitySymbol.PositionAndShape);
     }
 
+    /**
+     * True iff [[StaffLine]] belongs to an [[Instrument]] with more than one [[Staff]].
+     * @returns {boolean}
+     */
     public isPartOfMultiStaffInstrument(): boolean {
         let instrument: Instrument = this.parentStaff.ParentInstrument;
         if (instrument.Staves.length > 1) {
@@ -92,6 +96,11 @@ export abstract class StaffLine extends GraphicalObject {
         return false;
     }
 
+    /**
+     * Find the [[GraphicalStaffEntry]] closest to the given xPosition.
+     * @param xPosition
+     * @returns {GraphicalStaffEntry}
+     */
     public findClosestStaffEntry(xPosition: number): GraphicalStaffEntry {
         let closestStaffentry: GraphicalStaffEntry = undefined;
         let difference: number = Number.MAX_VALUE;

src/MusicalScore/Graphical/StaffLineActivitySymbol.ts

@@ -3,6 +3,7 @@ import {StaffLine} from "./StaffLine";
 import {BoundingBox} from "./BoundingBox";
 
 export class StaffLineActivitySymbol extends GraphicalObject {
+
     constructor(staffLine: StaffLine) {
         super();
         this.parentStaffLine = staffLine;
@@ -13,5 +14,7 @@ export class StaffLineActivitySymbol extends GraphicalObject {
         this.boundingBox.BorderLeft = -1.5;
         this.boundingBox.BorderTop = -1.5;
     }
+
     public parentStaffLine: StaffLine;
+
 }

src/MusicalScore/Graphical/StaffMeasure.ts

@@ -44,9 +44,21 @@ export abstract class StaffMeasure extends GraphicalObject {
     public parentSourceMeasure: SourceMeasure;
     public staffEntries: GraphicalStaffEntry[];
     public parentMusicSystem: MusicSystem;
+    /**
+     * The x-width of possibly existing: repetition start line, clef, key, rhythm.
+     */
     public beginInstructionsWidth: number;
+    /**
+     * The minimum possible x-width of all staff entries without overlapping.
+     */
     public minimumStaffEntriesWidth: number;
+    /**
+     * Will be set by music system builder while building systems.
+     */
     public staffEntriesScaleFactor: number;
+    /**
+     * The x-width of possibly existing: repetition end line, clef.
+     */
     public endInstructionsWidth: number;
     public hasError: boolean;
 
@@ -89,38 +101,81 @@ export abstract class StaffMeasure extends GraphicalObject {
         }
     }
 
+    /**
+     * Reset all the geometric values and parameters of this measure and put it in an initialized state.
+     * This is needed to evaluate a measure a second time by system builder.
+     */
     public resetLayout(): void {
         throw new Error("not implemented");
     }
 
+    /**
+     * Return the x-width of a given measure line.
+     * @param line
+     */
     public getLineWidth(line: SystemLinesEnum): number {
         throw new Error("not implemented");
     }
 
+    /**
+     * Add the given clef to the begin of the measure.
+     * This has to update/increase BeginInstructionsWidth.
+     * @param clef
+     */
     public addClefAtBegin(clef: ClefInstruction): void {
         throw new Error("not implemented");
     }
 
+    /**
+     * Add the given key to the begin of the measure.
+     * This has to update/increase BeginInstructionsWidth.
+     * @param currentKey - The new valid key.
+     * @param previousKey - The old cancelled key. Needed to show which accidentals are not valid any more.
+     * @param currentClef - The valid clef. Needed to put the accidentals on the right y-positions.
+     */
     public addKeyAtBegin(currentKey: KeyInstruction, previousKey: KeyInstruction, currentClef: ClefInstruction): void {
         throw new Error("not implemented");
     }
 
+    /**
+     * Add the given rhythm to the begin of the measure.
+     * This has to update/increase BeginInstructionsWidth.
+     * @param rhythm
+     */
     public addRhythmAtBegin(rhythm: RhythmInstruction): void {
         throw new Error("not implemented");
     }
 
+    /**
+     * Add the given clef to the end of the measure.
+     * This has to update/increase EndInstructionsWidth.
+     * @param clef
+     */
     public addClefAtEnd(clef: ClefInstruction): void {
         throw new Error("not implemented");
     }
 
+    /**
+     * Set the x-position relative to the staffline (y-Position is always 0 relative to the staffline).
+     * @param xPos
+     */
     public setPositionInStaffline(xPos: number): void {
         this.PositionAndShape.RelativePosition = new PointF2D(xPos, 0);
     }
 
+    /**
+     * Set the overall x-width of the measure.
+     * @param width
+     */
     public setWidth(width: number): void {
         this.PositionAndShape.BorderRight = width;
     }
 
+    /**
+     * This method is called after the StaffEntriesScaleFactor has been set.
+     * Here the final x-positions of the staff entries have to be set.
+     * (multiply the minimal positions with the scaling factor, considering the BeginInstructionsWidth).
+     */
     public layoutSymbols(): void {
         throw new Error("not implemented");
     }
@@ -135,6 +190,11 @@ export abstract class StaffMeasure extends GraphicalObject {
         return undefined;
     }
 
+    /**
+     * Iterate from start to end and find the [[GraphicalStaffEntry]] with the same absolute timestamp.
+     * @param absoluteTimestamp
+     * @returns {any}
+     */
     public findGraphicalStaffEntryFromVerticalContainerTimestamp(absoluteTimestamp: Fraction): GraphicalStaffEntry {
         for (let idx: number = 0, len: number = this.staffEntries.length; idx < len; ++idx) {
             let graphicalStaffEntry: GraphicalStaffEntry = this.staffEntries[idx];
@@ -145,6 +205,10 @@ export abstract class StaffMeasure extends GraphicalObject {
         return undefined;
     }
 
+    /**
+     * Check if the all the [[GraphicalMeasure]]'s [[StaffEntry]]s (their minimum Length) have the same duration with the [[SourceMeasure]].
+     * @returns {boolean}
+     */
     public hasSameDurationWithSourceMeasureParent(): boolean {
         let duration: Fraction = new Fraction(0, 1);
         for (let idx: number = 0, len: number = this.staffEntries.length; idx < len; ++idx) {
@@ -154,6 +218,10 @@ export abstract class StaffMeasure extends GraphicalObject {
         return duration.Equals(this.parentSourceMeasure.Duration);
     }
 
+    /**
+     * Check a whole [[Measure]] for the presence of multiple Voices (used for Stem direction).
+     * @returns {boolean}
+     */
     public hasMultipleVoices(): boolean {
         if (this.staffEntries.length === 0) {
             return false;
@@ -214,6 +282,10 @@ export abstract class StaffMeasure extends GraphicalObject {
         this.PositionAndShape.ChildElements.push(graphicalStaffEntry.PositionAndShape);
     }
 
+    /**
+     * Add a [[StaffEntry]] (along with its [[BoundingBox]]) to the current Measure.
+     * @param staffEntry
+     */
     public addGraphicalStaffEntryAtTimestamp(staffEntry: GraphicalStaffEntry): void {
         if (staffEntry !== undefined) {
             if (this.staffEntries.length === 0 || this.staffEntries[this.staffEntries.length - 1].relInMeasureTimestamp.lt(staffEntry.relInMeasureTimestamp)) {
@@ -241,6 +313,10 @@ export abstract class StaffMeasure extends GraphicalObject {
         return sourceMeasure.beginsWithLineRepetition();
     }
 
+    /**
+     * Check if this Measure is a Repetition Ending.
+     * @returns {boolean}
+     */
     public endsWithLineRepetition(): boolean {
         let sourceMeasure: SourceMeasure = this.parentSourceMeasure;
         if (sourceMeasure === undefined) {
@@ -249,6 +325,10 @@ export abstract class StaffMeasure extends GraphicalObject {
         return sourceMeasure.endsWithLineRepetition();
     }
 
+    /**
+     * Check if a Repetition starts at the next Measure.
+     * @returns {boolean}
+     */
     public beginsWithWordRepetition(): boolean {
         let sourceMeasure: SourceMeasure = this.parentSourceMeasure;
         if (sourceMeasure === undefined) {
@@ -257,6 +337,9 @@ export abstract class StaffMeasure extends GraphicalObject {
         return sourceMeasure.beginsWithWordRepetition();
     }
 
+    /**
+     * Check if this Measure is a Repetition Ending.
+     */
     public endsWithWordRepetition(): boolean {
         let sourceMeasure: SourceMeasure = this.parentSourceMeasure;
         if (sourceMeasure === undefined) {

src/MusicalScore/Graphical/SystemLine.ts

@@ -6,7 +6,9 @@ import {SystemLinesEnum} from "./SystemLinesEnum";
 import {BoundingBox} from "./BoundingBox";
 import {GraphicalObject} from "./GraphicalObject";
 import {EngravingRules} from "./EngravingRules";
+
 export class SystemLine extends GraphicalObject {
+
     constructor(lineType: SystemLinesEnum, linePosition: SystemLinePosition, musicSystem: MusicSystem,
                 topMeasure: StaffMeasure, bottomMeasure: StaffMeasure = undefined) {
         super();
@@ -18,12 +20,20 @@ export class SystemLine extends GraphicalObject {
         this.parentTopStaffLine = topMeasure.ParentStaffLine;
         this.boundingBox = new BoundingBox(this, musicSystem.PositionAndShape);
     }
+
     public lineType: SystemLinesEnum;
     public linePosition: SystemLinePosition;
     public parentMusicSystem: MusicSystem;
     public parentTopStaffLine: StaffLine;
     public topMeasure: StaffMeasure;
     public bottomMeasure: StaffMeasure;
+
+    /**
+     * Return the width of the SystemLinesContainer for the given SystemLineType.
+     * @param rules
+     * @param systemLineType
+     * @returns {number}
+     */
     public static getObjectWidthForLineType(rules: EngravingRules, systemLineType: SystemLinesEnum): number {
         switch (systemLineType) {
             case SystemLinesEnum.SingleThin:
@@ -45,4 +55,5 @@ export class SystemLine extends GraphicalObject {
                 return 0;
         }
     }
+
 }

src/MusicalScore/Graphical/VerticalGraphicalStaffEntryContainer.ts

@@ -2,11 +2,10 @@ import {Fraction} from "../../Common/DataObjects/Fraction";
 import {GraphicalStaffEntry} from "./GraphicalStaffEntry";
 
 export class VerticalGraphicalStaffEntryContainer {
+
     constructor(numberOfEntries: number, absoluteTimestamp: Fraction) {
         this.absoluteTimestamp = absoluteTimestamp;
-        for (let i: number = 0; i < numberOfEntries; i++) {
-            this.staffEntries.push(undefined);
-        }
+        this.staffEntries = new Array(numberOfEntries);
     }
 
     //public relativeInMeasureTimestamp: Fraction;
@@ -25,7 +24,7 @@ export class VerticalGraphicalStaffEntryContainer {
     public get AbsoluteTimestamp(): Fraction {
         return this.absoluteTimestamp;
     }
-    //
+
     //public set AbsoluteTimestamp(value: Fraction) {
     //    this.absoluteTimestamp = value;
     //}
@@ -51,6 +50,10 @@ export class VerticalGraphicalStaffEntryContainer {
         }
     }
 
+    /**
+     * Return the first non-null [[GraphicalStaffEntry]].
+     * @returns {any}
+     */
     public getFirstNonNullStaffEntry(): GraphicalStaffEntry {
         for (let idx: number = 0, len: number = this.staffEntries.length; idx < len; ++idx) {
             let graphicalStaffEntry: GraphicalStaffEntry = this.staffEntries[idx];