JSDoc all the things!

lib/src/lifecycle/AppClass.ts

@@ -3,10 +3,18 @@ import {DependencyKey} from '../../../di/src/type/DependencyKey.ts'
 import {make} from '../../../di/src/global.ts'
 import Application from '../lifecycle/Application.ts'
 
+/**
+ * Base type for a class that supports binding methods by string.
+ */
 export interface Bindable {
     get_bound_method(method_name: string): (...args: any[]) => any
 }
 
+/**
+ * Returns true if the given object is bindable.
+ * @param what
+ * @return boolean
+ */
 export function isBindable(what: any): what is Bindable {
     return (
         what
@@ -16,23 +24,50 @@ export function isBindable(what: any): what is Bindable {
     )
 }
 
+/**
+ * Base class for Daton-interactive classes. Provides helpful utilities for accessing
+ * the underlying application and IoC container.
+ */
 export default class AppClass {
+    /**
+     * Use the IoC container to create an instance of the given class.
+     * @param {Instantiable|DependencyKey} target - the key to instantiate
+     * @param {...any} parameters - parameters to pass to the constructor
+     */
     protected static make<T>(target: Instantiable<T>|DependencyKey, ...parameters: any[]) {
         return make(target, ...parameters)
     }
 
+    /**
+     * Get the Daton app.
+     * @type Application
+     */
     protected static get app() {
         return make(Application)
     }
 
+    /**
+     * Use the IoC container to create an instance of the given class.
+     * @param {Instantiable|DependencyKey} target - the key to instantiate
+     * @param {...any} parameters - parameters to pass to the constructor
+     */
     protected make<T>(target: Instantiable<T>|DependencyKey, ...parameters: any[]) {
         return make(target, ...parameters)
     }
 
+    /**
+     * Get the Daton app.
+     * @type Application
+     */
     protected get app() {
         return make(Application)
     }
 
+    /**
+     * Get the method with the given name from this class, bound to this class.
+     * @param {string} method_name
+     * @return function
+     */
     public get_bound_method(method_name: string): (...args: any[]) => any {
         // @ts-ignore
         if ( typeof this[method_name] !== 'function' ) {

lib/src/lifecycle/Application.ts

@@ -9,24 +9,47 @@ import Instantiable from '../../../di/src/type/Instantiable.ts'
 import {Collection} from '../collection/Collection.ts'
 import {path} from '../external/std.ts'
 
+/**
+ * Central class for Daton applications.
+ */
 @Service()
 export default class Application {
+    /**
+     * Collection of LifecycleUnits instantiated by this application.
+     * @type Collection<LifecycleUnit>
+     */
     protected instantiated_units: Collection<LifecycleUnit> = new Collection<LifecycleUnit>()
 
     constructor(
         protected logger: Logging,
         protected rleh: RunLevelErrorHandler,
+        /**
+         * Array of unit classes to run for this application.
+         * @type Array<Instantiable<LifecycleUnit>>
+         */
         protected units: (Instantiable<LifecycleUnit>)[],
     ) {}
 
+    /**
+     * Use the IoC container to instantiate the given dependency key.
+     * @param {DependencyKey} token
+     */
     make(token: DependencyKey) {
         return make(token)
     }
 
+    /**
+     * Get the IoC container.
+     * @return Container
+     */
     container() {
         return container
     }
 
+    /**
+     * Launch the application.
+     * @return Promise<void>
+     */
     async up() {
         this.logger.info('Starting Daton...', true)
         for ( const unit_class of this.units ) {
@@ -36,10 +59,18 @@ export default class Application {
         }
     }
 
+    /**
+     * Stop the application.
+     * @return Promise<void>
+     */
     async down() {
 
     }
 
+    /**
+     * Run the application.
+     * @return Promise<void>
+     */
     async run() {
         try {
             await this.up()
@@ -49,10 +80,18 @@ export default class Application {
         }
     }
 
+    /**
+     * Pass an error to the top-level error handler.
+     * @param {Error} e
+     */
     async app_error(e: Error) {
         this.rleh.handle(e)
     }
 
+    /**
+     * Launch the given lifecycle unit.
+     * @param {LifecycleUnit} unit
+     */
     protected async start_unit(unit: LifecycleUnit) {
         try {
             unit.status = Status.Starting
@@ -68,18 +107,36 @@ export default class Application {
         }
     }
 
+    /**
+     * Get the root directory of the application.
+     * @type string
+     */
     get root() {
         return path.resolve('.')
     }
 
+    /**
+     * Get the root directory of application class definitions.
+     * @type string
+     */
     get app_root() {
         return path.resolve('./app')
     }
 
+    /**
+     * Resolve the given path within the application's root.
+     * @param {...string} parts
+     * @return string
+     */
     path(...parts: string[]) {
         return path.resolve(this.root, ...parts)
     }
 
+    /**
+     * Resolve the given path within the application's class definition root.
+     * @param {...string} parts
+     * @return string
+     */
     app_path(...parts: string[]) {
         return path.resolve(this.app_root, ...parts)
     }

lib/src/lifecycle/Unit.ts

@@ -1,28 +1,62 @@
-import { Status, isStatus } from '../const/status.ts'
+import { Status } from '../const/status.ts'
 import { Collection } from '../collection/Collection.ts'
-import {container, make} from '../../../di/src/global.ts'
-import {DependencyKey} from '../../../di/src/type/DependencyKey.ts'
-import Instantiable, {isInstantiable} from '../../../di/src/type/Instantiable.ts'
+import {container} from '../../../di/src/global.ts'
+import {isInstantiable} from '../../../di/src/type/Instantiable.ts'
 import AppClass from './AppClass.ts'
 
+/**
+ * Returns true if the given item is a lifecycle unit.
+ * @param something
+ * @return boolean
+ */
 const isLifecycleUnit = (something: any): something is (typeof LifecycleUnit) => {
     return isInstantiable(something) && something.prototype instanceof LifecycleUnit
 }
 
+/**
+ * Base class representing a single unit of the application lifecycle, responsible
+ * for booting and stopping some piece of the application.
+ * @extends AppClass
+ */
 export default abstract class LifecycleUnit extends AppClass {
+    /**
+     * The current status of the unit.
+     * @type Status
+     */
     private _status = Status.Stopped
 
+    /**
+     * Get the current status of the unit.
+     * @type Status
+     */
     public get status() {
         return this._status
     }
 
+    /**
+     * Set the current status of the unit.
+     * @param {Status} status
+     */
     public set status(status) {
         this._status = status
     }
 
+    /**
+     * Method called to boot and start the unit when the application is starting.
+     * @return Promise<void>
+     */
     public async up(): Promise<void> {};
+
+    /**
+     * Method called to stop the unit when the application is stopping.
+     * @return Promise<void>
+     */
     public async down(): Promise<void> {};
 
+    /**
+     * Returns a collection of lifecycle units that this lifecycle unit depends on.
+     * @return Collection<typeof LifecycleUnit>
+     */
     public static get_dependencies(): Collection<typeof LifecycleUnit> {
         if ( isInstantiable(this) ) {
             const deps = new Collection<typeof LifecycleUnit>()

lib/src/lifecycle/decorators.ts

@@ -2,6 +2,10 @@ import { Service } from '../../../di/src/decorator/Service.ts'
 
 const service = Service()
 
+/**
+ * Class decorator that designates a class as a lifecycle unit. Also applies the service decorator.
+ * @constructor
+ */
 const Unit = (): ClassDecorator => {
     return (target) => {
         return service(target)