Adds/improves tsdoc comments on a lot of core classes (#915)

Author: cspotcode

src/lib/utils/__events.ts

@@ -4,6 +4,9 @@ import { Application } from '../application';
 import { EventDispatcher, Event, EventMap } from './events';
 import { DeclarationOption } from './options/declaration';
 
+/**
+ * Exposes a reference to the root Application component.
+ */
 export interface ComponentHost {
     readonly application: Application;
 }
@@ -16,14 +19,21 @@ export interface ComponentClass<T extends Component, O extends ComponentHost = C
     new(owner: O): T;
 }
 
+/**
+ * Option-bag passed to Component decorator.
+ */
 export interface ComponentOptions {
     name?: string;
+    /** Specify valid child component class.  Used to prove that children are valid via `instanceof` checks */
     childClass?: Function;
     internal?: boolean;
 }
 
 const childMappings: {host: ChildableComponent<any, any>, child: Function}[] = [];
 
+/**
+ * Class decorator applied to Components
+ */
 export function Component(options: ComponentOptions): ClassDecorator {
     return (target: Function) => {
         const proto = target.prototype;
@@ -63,6 +73,11 @@ export function Component(options: ComponentOptions): ClassDecorator {
     };
 }
 
+/**
+ * Decorator that declares a configuration option.
+ *
+ * Use it on an instance property of a Component class.
+ */
 export function Option(options: DeclarationOption): PropertyDecorator {
     return function(target: object, propertyKey: string | symbol) {
         if (!(target instanceof AbstractComponent)) {
@@ -107,7 +122,10 @@ export class ComponentEvent extends Event {
 export const DUMMY_APPLICATION_OWNER = Symbol();
 
 /**
- * Component base class.
+ * Component base class.  Has an owner (unless it's the application root component),
+ * can dispatch events to its children, and has access to the root Application component.
+ *
+ * @template O type of component's owner.
  */
 export abstract class AbstractComponent<O extends ComponentHost> extends EventDispatcher implements ComponentHost {
     /**
@@ -176,7 +194,10 @@ export abstract class AbstractComponent<O extends ComponentHost> extends EventDi
 }
 
 /**
- * Component base class.
+ * Component that can have child components.
+ *
+ * @template O type of Component's owner
+ * @template C type of Component's children
  */
 export abstract class ChildableComponent<O extends ComponentHost, C extends Component> extends AbstractComponent<O> {
     /**

src/lib/utils/component.ts

@@ -15,7 +15,7 @@ export enum LogLevel {
 /**
  * A logger that will not produce any output.
  *
- * This logger also serves as the ase calls of other loggers as it implements
+ * This logger also serves as the base class of other loggers as it implements
  * all the required utility functions.
  */
 export class Logger {

src/lib/utils/loggers.ts

@@ -20,6 +20,8 @@ export enum ParameterScope {
 }
 
 /**
+ * Option-bag passed to Option decorator.
+ *
  * TODO: This should be a union type of multiple possible option types.
  */
 export interface DeclarationOption {
@@ -36,6 +38,10 @@ export interface DeclarationOption {
     convert?: (param: OptionDeclaration, value?: any) => any;
 }
 
+/**
+ * Runtime structure describing a configuration option.
+ * Used by option parsing and validation.
+ */
 export class OptionDeclaration {
     name!: string;
 

src/lib/utils/options/declaration.ts

@@ -7,6 +7,14 @@ import { Component, AbstractComponent, ChildableComponent } from '../component';
 import { Application } from '../../application';
 import { OptionDeclaration, DeclarationOption, ParameterScope } from './declaration';
 
+/**
+ * Child of the master Options component.  Options === configuration
+ *
+ * Serves one of two roles:
+ *
+ * - Aggregates and contributes configuration declarations declared by components or plugins
+ * - Parses option values from various sources (config file, command-line args, etc)
+ */
 export class OptionsComponent extends AbstractComponent<Options> { }
 
 export enum OptionsReadMode {
@@ -51,6 +59,10 @@ export class DiscoverEvent extends Event {
     }
 }
 
+/**
+ * Responsible for loading options via child components that read options
+ * from various sources.
+ */
 @Component({name: 'options', internal: true, childClass: OptionsComponent})
 export class Options extends ChildableComponent<Application, OptionsComponent> {
     private declarations!: {[name: string]: OptionDeclaration};

src/lib/utils/options/options.ts

@@ -5,6 +5,9 @@ import { Component } from '../../component';
 import { DiscoverEvent, OptionsComponent } from '../options';
 import { ParameterType } from '../declaration';
 
+/**
+ * Obtains option values from command-line arguments
+ */
 @Component({name: 'options:arguments'})
 export class ArgumentsReader extends OptionsComponent {
     initialize() {

src/lib/utils/options/readers/arguments.ts

@@ -8,6 +8,9 @@ import { OptionsComponent, OptionsReadMode, DiscoverEvent } from '../options';
 import { ParameterType, ParameterHint } from '../declaration';
 import { TypeScriptSource } from '../sources/typescript';
 
+/**
+ * Obtains option values from tsconfig.json
+ */
 @Component({name: 'options:tsconfig'})
 export class TSConfigReader extends OptionsComponent {
     @Option({

src/lib/utils/options/readers/tsconfig.ts

@@ -6,6 +6,9 @@ import { Component, Option } from '../../component';
 import { OptionsComponent, OptionsReadMode, DiscoverEvent } from '../options';
 import { ParameterType, ParameterHint } from '../declaration';
 
+/**
+ * Obtains option values from typedoc.js
+ */
 @Component({name: 'options:typedoc'})
 export class TypedocReader extends OptionsComponent {
     @Option({

src/lib/utils/options/readers/typedoc.ts

@@ -1,6 +1,12 @@
 import { Component, ComponentEvent, AbstractComponent, ChildableComponent } from '../../component';
 import { OptionsComponent } from '../options';
 
+/**
+ * Aggregates options declared by other components.
+ *
+ * Listens for when a component is added and adds the component's declared
+ * options to the `Options` component.
+ */
 @Component({name: 'options:component'})
 export class ComponentSource extends OptionsComponent {
     private knownComponents!: string[];

src/lib/utils/options/sources/component.ts

@@ -5,6 +5,12 @@ import { Component } from '../../component';
 import { OptionsComponent } from '../options';
 import { DeclarationOption, ParameterScope, ParameterType, ParameterHint } from '../declaration';
 
+/**
+ * Discovers and contributes options declared by TypeScript.
+ *
+ * typedoc accepts many of the same options as TypeScript itself, so they must be parsed
+ * from TypeScript's metadata and declared on typedoc's Option parser.
+ */
 @Component({name: 'options:typescript'})
 export class TypeScriptSource extends OptionsComponent {
     private declarations!: DeclarationOption[];

src/lib/utils/options/sources/typescript.ts

@@ -3,9 +3,14 @@ import { Minimatch, IMinimatch } from 'minimatch';
 
 const unix = Path.sep === '/';
 
+/**
+ * Convert array of glob patterns to array of minimatch instances.
+ *
+ * Handle a few Windows-Unix path gotchas.
+ */
 export function createMinimatch(patterns: string[]): IMinimatch[] {
     return patterns.map((pattern: string): IMinimatch => {
-        // Ensure correct pathing on unix, by transforming `\` to `/` and remvoing any `X:/` fromt he path
+        // Ensure correct pathing on unix, by transforming `\` to `/` and removing any `X:/` from the path
         if (unix) { pattern = pattern.replace(/[\\]/g, '/').replace(/^\w:/, ''); }
 
         // pattern paths not starting with '**' are resolved even if it is an
@@ -17,7 +22,7 @@ export function createMinimatch(patterns: string[]): IMinimatch[] {
         // On Windows we transform `\` to `/` to unify the way paths are intepreted
         if (!unix) { pattern = pattern.replace(/[\\]/g, '/'); }
 
-        // Unify the path slashes before creating the minimatch, for more relyable matching
+        // Unify the path slashes before creating the minimatch, for more reliable matching
         return new Minimatch(pattern, { dot: true });
     });
 }

src/lib/utils/paths.ts

@@ -5,6 +5,9 @@ import { Application } from '../application';
 import { AbstractComponent, Component, Option } from './component';
 import { ParameterType } from './options/declaration';
 
+/**
+ * Responsible for discovering and loading plugins.
+ */
 @Component({ name: 'plugin-host', internal: true })
 export class PluginHost extends AbstractComponent<Application> {
     @Option({