Add docs, setWidth, one bug fixed

Document everything in timeSignature.ts

Add general documentation for what StaveModifier.placeGlyphOnLine does.

Reset width any time Glyph is changed

Fix one bug in TimeSigGlyph where the `.line` of the TimeSignature was being ignored.

Author: mscuthbert

src/stavemodifier.ts

@@ -90,6 +90,15 @@ export class StaveModifier extends Element {
     return this;
   }
 
+  /**
+   * Runs setYShift() for the Glyph object so that it matches the position of line for
+   * the Stave provided.  A `customShift` can also be given (measured in the same units
+   * as `setYShift` not in lines) and this will be added after all other positions are
+   * calculated from the Stave.
+   *
+   * Note that this routine only sets the yShift; it does not actually "place" (meaning
+   * draw) the Glyph on the Stave.  Call .draw() afterwards to do that.
+   */
   placeGlyphOnLine(glyph: Glyph, stave: Stave, line?: number, customShift = 0): void {
     glyph.setYShift(stave.getYForLine(line ?? 0) - stave.getYForGlyphs() + customShift);
   }

src/timesigglyph.ts

@@ -104,7 +104,7 @@ export class TimeSignatureGlyph extends Glyph {
     y = stave.getYForLine(this.timeSignature.bottomLine);
     for (let i = 0; i < this.botGlyphs.length; ++i) {
       const glyph = this.botGlyphs[i];
-      this.timeSignature.placeGlyphOnLine(glyph, stave, 0);
+      this.timeSignature.placeGlyphOnLine(glyph, stave, this.timeSignature.getLine());
       Glyph.renderOutline(ctx, glyph.getMetrics().outline, this.scale, start_x + glyph.getMetrics().x_shift, y);
       start_x += defined(glyph.getMetrics().width);
     }

src/timesignature.ts

@@ -36,6 +36,11 @@ const assertIsValidTimeSig = (timeSpec: string) => {
   });
 };
 
+/**
+ * A TimeSignature is a StaveModifier that can make its appropriate Glyphs directly from
+ * a provided "timeSpec" such as "4/4", "C|" (cut time), or even something more advanced
+ * such as "3/4(6/8)" or "2/4+5/8".
+ */
 export class TimeSignature extends StaveModifier {
   static get CATEGORY(): string {
     return Category.TimeSignature;
@@ -57,8 +62,8 @@ export class TimeSignature extends StaveModifier {
   }
 
   point: number;
-  bottomLine: number;
-  topLine: number;
+  bottomLine: number; // bottomLine and topLine are used to calculate the position of the
+  topLine: number; // top row of digits in a numeric TimeSignature.
 
   protected timeSpec: string = '4/4';
   protected line: number = 0;
@@ -81,10 +86,14 @@ export class TimeSignature extends StaveModifier {
     this.bottomLine = 4 + fontLineShift;
     this.setPosition(StaveModifierPosition.BEGIN);
     this.setTimeSig(timeSpec);
-    this.setWidth(defined(this.glyph.getMetrics().width));
     this.setPadding(padding);
   }
 
+  /**
+   * Return TimeSignatureInfo given a string, consisting of line (number),
+   * num (boolean: same as TimeSignature.getIsNumeric()), and glyph (a Glyph or
+   * TimeSignatureGlyph object).
+   */
   parseTimeSpec(timeSpec: string): TimeSignatureInfo {
     if (timeSpec === 'C' || timeSpec === 'C|') {
       const { line, code, point } = TimeSignature.glyphs[timeSpec];
@@ -108,12 +117,18 @@ export class TimeSignature extends StaveModifier {
     };
   }
 
-  makeTimeSignatureGlyph(topDigits: string, botDigits: string): Glyph {
+  /**
+   * Returns a new TimeSignatureGlyph (a Glyph subclass that knows how to draw both
+   * top and bottom digits along with plus signs etc.)
+   */
+  makeTimeSignatureGlyph(topDigits: string, botDigits: string): TimeSignatureGlyph {
+    // note that 'code' is ignored by TimeSignatureGlyph when rendering.
     return new TimeSignatureGlyph(this, topDigits, botDigits, 'timeSig0', this.point);
   }
 
   /**
-   * Returns line, num, glyph -- but these can be accessed directly w/ getters and setters.
+   * Returns {line, num (=getIsNumeric), glyph} --
+   * but these can also be accessed directly w/ getters and setters.
    */
   getInfo(): TimeSignatureInfo {
     const { line, is_numeric, glyph } = this;
@@ -128,40 +143,72 @@ export class TimeSignature extends StaveModifier {
   setTimeSig(timeSpec: string): this {
     this.timeSpec = timeSpec;
     const info = this.parseTimeSpec(timeSpec);
-    this.glyph = info.glyph;
+    this.setGlyph(info.glyph);
     this.is_numeric = info.num;
     this.line = info.line;
     return this;
   }
 
+  /**
+   * Return the timeSpec (such as '4/4' or 'C|' or even '2/4+3/8') of the TimeSignature
+   */
   getTimeSpec(): string {
     return this.timeSpec;
   }
 
+  /**
+   * Return the staff line that the TimeSignature sits on.  Generally 0 for numerator/
+   * denominator time signatures such as 3/4 and 2 for cut/common.
+   */
   getLine(): number {
     return this.line;
   }
 
+  /**
+   * Set the line number that the TimeSignature sits on.  Half-values are acceptable
+   * for spaces, etc. Can be altered, for instance, for signatures that sit above the
+   * staff in large orchestral scores.
+   */
   setLine(line: number) {
     this.line = line;
   }
 
+  /**
+   * Get the Glyph object used to create the time signature.  Numeric time signatures
+   * such as 3/8 have a composite Glyph stored as a single Glyph object.
+   */
   getGlyph(): Glyph {
     return this.glyph;
   }
 
+  /**
+   * Set the Glyph object used to draw the time signature, and update the width of the
+   * TimeSignature to match.  The Glyph must define width in its metrics.
+   */
   setGlyph(glyph: Glyph) {
     this.glyph = glyph;
+    this.setWidth(defined(this.glyph.getMetrics().width));
   }
 
+  /**
+   * Return a boolean on whether this TimeSignature is drawn with one or more numbers
+   * (such as 4/4) or not (as in cut time).
+   */
   getIsNumeric(): boolean {
     return this.is_numeric;
   }
 
+  /**
+   * Set whether this TimeSignature is drawn with one or more numbers.
+   */
   setIsNumeric(isNumeric: boolean) {
     this.is_numeric = isNumeric;
   }
 
+  /**
+   * Draw the time signature on a Stave using its RenderContext.  Both setStave
+   * and setContext must already be run.
+   */
   draw(): void {
     const stave = this.checkStave();
     const ctx = stave.checkContext();