feat(TestScheduler): expose frameTimeFactor property (#4977)

- Makes `frameTimeFactor` public so people do not have to cast in TypeScript
- Deprecates `frameTimeFactor` on `VirtualTimeScheduler` as it is not used in that class, it
is really only intended to be used for `TestScheduler` marble diagrams
- Deprecates `index` on `VirtualTimeScheduler` because it is a leaked implementation detail
- Adds documentation

Author: benlesh

spec/schedulers/TestScheduler-spec.ts

@@ -14,6 +14,10 @@ describe('TestScheduler', () => {
     expect(TestScheduler).to.be.a('function');
   });
 
+  it('should have frameTimeFactor set initially', () => {
+    expect(TestScheduler.frameTimeFactor).to.equal(10);
+  });
+
   describe('parseMarbles()', () => {
     it('should parse a marble string into a series of notifications and types', () => {
       const result = TestScheduler.parseMarbles('-------a---b---|', { a: 'A', b: 'B' });

src/internal/scheduler/VirtualTimeScheduler.ts

@@ -5,11 +5,30 @@ import { SchedulerAction } from '../types';
 
 export class VirtualTimeScheduler extends AsyncScheduler {
 
-  protected static frameTimeFactor: number = 10;
+  /** @deprecated remove in v8. `frameTimeFactor` is not used in VirtualTimeScheduler directly. */
+  static frameTimeFactor = 10;
 
+  /**
+   * The current frame for the state of the virtual scheduler instance. The the difference
+   * between two "frames" is synonymous with the passage of "virtual time units". So if
+   * you record `scheduler.frame` to be `1`, then later, observe `scheduler.frame` to be at `11`,
+   * that means `10` virtual time units have passed.
+   */
   public frame: number = 0;
+
+  /**
+   * Used internally to examine the current virtual action index being processed.
+   * @deprecated remove in v8. Should be a private API.
+   */
   public index: number = -1;
 
+  /**
+   * This creates an instance of a `VirtualTimeScheduler`. Experts only. The signature of
+   * this constructor is likely to change in the long run.
+   *
+   * @param SchedulerAction The type of Action to initialize when initializing actions during scheduling.
+   * @param maxFrames The maximum number of frames to process before stopping. Used to prevent endless flush cycles.
+   */
   constructor(SchedulerAction: typeof AsyncAction = VirtualAction as any,
               public maxFrames: number = Number.POSITIVE_INFINITY) {
     super(SchedulerAction, () => this.frame);
@@ -43,10 +62,6 @@ export class VirtualTimeScheduler extends AsyncScheduler {
   }
 }
 
-/**
- * We need this JSDoc comment for affecting ESDoc.
- * @nodoc
- */
 export class VirtualAction<T> extends AsyncAction<T> {
 
   protected active: boolean = true;

src/internal/testing/TestScheduler.ts

@@ -28,11 +28,38 @@ export type observableToBeFn = (marbles: string, values?: any, errorValue?: any)
 export type subscriptionLogsToBeFn = (marbles: string | string[]) => void;
 
 export class TestScheduler extends VirtualTimeScheduler {
+  /**
+   * The number of virtual time units each character in a marble diagram represents. If
+   * the test scheduler is being used in "run mode", via the `run` method, this is temporarly
+   * set to `1` for the duration of the `run` block, then set back to whatever value it was.
+   */
+  static frameTimeFactor = 10;
+
+  /**
+   * @deprecated remove in v8. Not for public use.
+   */
   public readonly hotObservables: HotObservable<any>[] = [];
+
+  /**
+   * @deprecated remove in v8. Not for public use.
+   */
   public readonly coldObservables: ColdObservable<any>[] = [];
+
+  /**
+   * Test meta data to be processed during `flush()`
+   */
   private flushTests: FlushableTest[] = [];
+
+  /**
+   * Indicates whether the TestScheduler instance is operating in "run mode",
+   * meaning it's processing a call to `run()`
+   */
   private runMode = false;
 
+  /**
+   *
+   * @param assertDeepEqual A function to set up your assertion for your test harness
+   */
   constructor(public assertDeepEqual: (actual: any, expected: any) => boolean | void) {
     super(VirtualAction, defaultMaxFrame);
   }