Add API doc for 'BackendApplicationContribution'

Signed-off-by: Stefan Dirix <sdirix@eclipsesource.com>
Contributed on behalf of STMicroelectronics

packages/core/src/node/backend-application.ts

@@ -30,14 +30,48 @@ import { AddressInfo } from 'net';
 import { ApplicationPackage } from '@theia/application-package';
 
 export const BackendApplicationContribution = Symbol('BackendApplicationContribution');
+
+/**
+ * Entry point for hooking into the backend lifecycle.
+ */
 export interface BackendApplicationContribution {
-    initialize?(): void;
-    configure?(app: express.Application): void;
+    /**
+     * Called during the initialization of the backend application.
+     * Use this for functionality which has to run as early as possible.
+     *
+     * @returns Either `undefined` (i.e. void) or a Promise resolving to `undefined`.
+     * Note that returning a Promise will still block initialization as the Promise is awaited.
+     */
+    initialize?(): MaybePromise<void>;
+
+    /**
+     * Called after the initialization of the backend application is complete.
+     * Use this to configure the Express app before it is started, for example
+     * to offer additional endpoints.
+     *
+     * @param app the express application to configure.
+     *
+     * @returns Either `undefined` (i.e. void) or a Promise resolving to `undefined`.
+     * Note that returning a Promise will still block configuration as the Promise is awaited.
+     */
+    configure?(app: express.Application): MaybePromise<void>;
+
+    /**
+     * Called right after the server for the Express app is started.
+     * Use this to additionally configure the server or as ready-signal for your service.
+     *
+     * @param server the backend server running the express app.
+     *
+     * @returns Either `undefined` (i.e. void) or a Promise resolving to `undefined`.
+     * Note that returning a Promise will still block startup as the Promise is awaited.
+     */
     onStart?(server: http.Server | https.Server): MaybePromise<void>;
 
     /**
      * Called when the backend application shuts down. Contributions must perform only synchronous operations.
      * Any kind of additional asynchronous work queued in the event loop will be ignored and abandoned.
+     *
+     * @param app the express application.
      */
     onStop?(app?: express.Application): void;
 }