Add tsdoc package documentation

extensions/authentication-passport/src/index.ts

@@ -3,4 +3,22 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+/**
+ * An adapter to plug in passport based strategies to the authentication system
+ * in {@link @loopback/authentication# | @loopback/authentication @3.x }.
+ *
+ * @remarks
+ * {@link @loopback/authentication# | @loopback/authentication @3.x } allows
+ * users to register authentication strategies that implement the interface
+ * `AuthenticationStrategy`.
+ *
+ * Since AuthenticationStrategy describes a strategy with different contracts
+ * than the passport Strategy, and we'd like to support the existing 500+
+ * community passport strategies, an adapter class is created in this package to
+ * convert a passport strategy to the one that LoopBack 4 authentication system
+ * wants.
+ *
+ * @packageDocumentation
+ */
+
 export * from './strategy-adapter';

extensions/health/src/index.ts

@@ -3,6 +3,13 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+/**
+ * A component to report health status using
+ * {@link https://github.com/CloudNativeJS/cloud-health | @cloudnative/health }.
+ *
+ * @packageDocumentation
+ */
+
 export * from './health.component';
 export * from './keys';
 export * from './types';

extensions/logging/src/decorators/index.ts

@@ -3,4 +3,11 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+/**
+ * This module contains a component provides logging facilities based on Winston
+ * and Fluentd.
+ *
+ * @packageDocumentation
+ */
+
 export * from './logging.decorator';

extensions/logging/src/index.ts

@@ -3,6 +3,12 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+/**
+ * A component provides logging facilities based on
+ * {@link https://github.com/winstonjs/winston | Winston} and
+ * {@link https://github.com/fluent/fluent-logger-node | Fluentd}.
+ */
+
 export * from './decorators';
 export * from './keys';
 export * from './logging.component';

extensions/metrics/src/index.ts

@@ -3,6 +3,13 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+/**
+ * A component that reports metrics of Node.js, the LoopBack framework, and your
+ * application to Prometheus.
+ *
+ * @packageDocumentation
+ */
+
 export * from 'prom-client';
 export * from './keys';
 export * from './metrics.component';

packages/authentication/src/index.ts

@@ -3,6 +3,23 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+/**
+ * A LoopBack 4 component for authentication support.
+ *
+ * @remarks
+ * The core logic for the authentication layer in LoopBack 4.
+ *
+ * It contains:
+ *
+ *  - A decorator to express an authentication requirement on controller methods
+ *  - A provider to access method-level authentication metadata
+ *  - An action in the REST sequence to enforce authentication
+ *  - An extension point to discover all authentication strategies and handle
+ *    the delegation
+ *
+ * @packageDocumentation
+ */
+
 export * from './authentication.component';
 export * from './decorators';
 export * from './keys';

packages/authorization/src/index.ts

@@ -3,6 +3,17 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+/**
+ * A LoopBack 4 component for authorization support (Role based, Permission
+ * based, Vote based)
+ *
+ * @remarks
+ * To read on key building blocks read through
+ * {@link https://loopback.io/doc/en/lb4/Loopback-component-authorization.html |LoopBack authorization docs}
+ *
+ * @packageDocumentation
+ */
+
 export * from './authorization-component';
 export * from './authorize-interceptor';
 export * from './decorators/authorize';

packages/boot/src/index.ts

@@ -3,9 +3,33 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+/**
+ * A convention based project Bootstrapper and Booters for LoopBack
+ * Applications.
+ *
+ * @remarks
+ * A Booter is a class that can be bound to an Application and is called to
+ * perform a task before the Application is started. A Booter may have multiple
+ * phases to complete its task. The task for a convention based Booter is to
+ * discover and bind Artifacts (Controllers, Repositories, Models, etc.).
+ *
+ * An example task of a Booter may be to discover and bind all artifacts of a
+ * given type.
+ *
+ * A Bootstrapper is needed to manage the Booters and execute them. This is
+ * provided in this package. For ease of use, everything needed is packages
+ * using a BootMixin. This Mixin will add convenience methods such as `boot` and
+ * `booter`, as well as properties needed for Bootstrapper such as
+ * `projectRoot`. The Mixin also adds the `BootComponent` to your `Application`
+ * which binds the `Bootstrapper` and default `Booters` made available by this
+ * package.
+ *
+ * @packageDocumentation
+ */
+
+export * from './boot.component';
 export * from './booters';
 export * from './bootstrapper';
-export * from './boot.component';
 export * from './keys';
 export * from './mixins';
 export * from './types';

packages/booter-lb3app/src/index.ts

@@ -3,4 +3,16 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+/**
+ * Boot a LoopBack 3 application and expose its REST API via LoopBack 4.
+ *
+ * @remarks
+ * This package provides a way for LoopBack 3 developers to boot their LoopBack
+ * 3 application, convert the application's Swagger spec into OpenAPI v3, and
+ * then mount the application, including its spec, onto a target LoopBack 4
+ * application.
+ *
+ * @pakageDocumentation
+ */
+
 export * from './lb3app.booter.component';

packages/context/src/index.ts

@@ -3,6 +3,33 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+/**
+ * Facilities to manage artifacts and their dependencies using {@link Context}
+ * in your Node.js applications. It can be used independent of the LoopBack
+ * framework.
+ *
+ * @remarks
+ * This package exposes TypeScript/JavaScript APIs and decorators to register
+ * artifacts, declare dependencies, and resolve artifacts by keys. The
+ * {@link Context} also serves as an IoC container to support dependency
+ * injection.
+ * Context and Binding are the two core concepts. A context is a registry of
+ * bindings and each binding represents a resolvable artifact by the key.
+ *
+ * - Bindings can be fulfilled by a constant, a factory function, a class, or a
+ *   provider.
+ * - Bindings can be grouped by tags and searched by tags.
+ * - Binding scopes can be used to control how a resolved binding value is
+ *   shared.
+ * - Bindings can be resolved synchronously or asynchronously.
+ * - Provide {@link inject | @inject} and other variants of decorators to
+ *   express dependencies.
+ * - Support Constructor, property, and method injections.
+ * - Allow contexts to form a hierarchy to share or override bindings.
+ *
+ * @pakageDocumentation
+ */
+
 export * from '@loopback/metadata';
 export * from './binding';
 export * from './binding-config';
@@ -22,9 +49,9 @@ export * from './interception-proxy';
 export * from './interceptor';
 export * from './interceptor-chain';
 export * from './invocation';
+export * from './json-types';
 export * from './keys';
 export * from './provider';
 export * from './resolution-session';
 export * from './resolver';
 export * from './value-promise';
-export * from './json-types';

packages/core/src/index.ts

@@ -3,9 +3,18 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+/**
+ * The foundation of a LoopBack app.
+ *
+ * @remarks
+ * For a typical example of how to create a REST server with your application,
+ * see the {@link @loopback/rest#} package.
+ *
+ * @packageDocumentation
+ */
+
 // Re-export public Core API coming from dependencies
 export * from '@loopback/context';
-
 // Export APIs
 export * from './application';
 export * from './component';

packages/http-caching-proxy/src/index.ts

@@ -3,4 +3,36 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+/**
+ * A caching HTTP proxy for integration tests.
+ *
+ * @remarks
+ * **NOT SUITABLE FOR PRODUCTION USE!**
+ *
+ * Testing applications connecting to backend REST/SOAP services can be
+ * difficult: The backend service may be slow, apply rate limiting, etc.
+ * Integration tests become too slow in such case, which makes test-first
+ * development impractical.
+ *
+ * This can be addressed by setting up a snapshot-based mock server or using a
+ * caching HTTP client, but both of these solutions come with severe
+ * disadvantages:
+ *
+ * - When using a snapshot-based mock server, we must ensure that snapshots are
+ *   up-to-date with the actual backend implementation.
+ * - Caching at HTTP-client side requires non-trivial changes of the application
+ *   code.
+ *
+ * A filesystem-backed caching HTTP proxy offers a neat solution that combines
+ * caching and snapshots:
+ *
+ * - The first request is forwarded to the actual backend and the response is
+ *   stored as a snapshot.
+ * - Subsequent requests are served by the proxy using the cached snaphost.
+ * - Snapshot older than a configured time are discarded and the first next
+ *   request will fetch the real response from the backend.
+ *
+ * @packageDocumentation
+ */
+
 export * from './http-caching-proxy';

packages/http-server/src/index.ts

@@ -3,4 +3,13 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+/**
+ * HTTP / HTTPS server endpoints for LoopBack 4 apps.
+ *
+ * @remarks
+ * A package used by LoopBack 4 for creating HTTP / HTTPS server.
+ *
+ * @packageDocumentation
+ */
+
 export * from './http-server';

packages/metadata/src/index.ts

@@ -3,7 +3,26 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-export * from './types';
-export * from './reflect';
+/**
+ * A package with utilities to help developers implement
+ * {@link https://www.typescriptlang.org/docs/handbook/decorators.html |TypeScript decorators},
+ * define/merge metadata, and inspect metadata.
+ *
+ * @remarks
+ * Utilities:
+ *
+ * - Reflector: Wrapper of
+ *   {@link https://github.com/rbuckton/reflect-metadata | reflect-metadata}.
+ * - Decorator factories: A set of factories for class/method/property/parameter
+ *   decorators to apply metadata to a given class and its static or instance
+ *   members.
+ * - MetadataInspector: High level APIs to inspect a class and/or its members to
+ *   get metadata applied by decorators.
+ *
+ * @packageDocumentation
+ */
+
 export * from './decorator-factory';
 export * from './inspector';
+export * from './reflect';
+export * from './types';

packages/model-api-builder/src/index.ts

@@ -3,5 +3,17 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+/**
+ * A packge with types and helpers for packages contributing Model API builders.
+ *
+ * @remarks
+ * Provides a contract for extensions that contribute builders for repositories
+ * and controllers. Users provide both the model class and an extension. The
+ * extension is then used to build their repository and controller based on the
+ * model class.
+ *
+ * @packageDocumentation
+ */
+
 export * from './model-api-builder';
 export * from './model-api-config';

packages/openapi-spec-builder/src/index.ts

@@ -3,4 +3,22 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+/**
+ * A package to simplify creating OpenAPI specification documents in your tests
+ * using the builder pattern.
+ *
+ * @remarks
+ * Creating a full OpenAPI spec document in automated tests is rather
+ * cumbersome, long JSON-like objects pollute the test test code and make it
+ * difficult for readers to distinguish between what's important in the test and
+ * what's just shared OpenAPI boilerplate.
+ *
+ * OpenApiSpecBuilder utilizes
+ * {@link http://www.natpryce.com/articles/000714.html | Test Data Builder pattern}
+ * to provide a TypeScript/JavaScript API allowing users to create full OpenAPI
+ * Specification 3 documents in few lines of code.
+ *
+ * @packageDocumentation
+ */
+
 export * from './openapi-spec-builder';

packages/openapi-v3/src/index.ts

@@ -3,6 +3,21 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+/**
+ * Decorators that describe LoopBack artifacts as OpenAPI 3.0.0 metadata and
+ * utilities that transfer LoopBack metadata to OpenAPI 3.0.0 specifications.
+ *
+ * @remarks
+ * The package has functions described above for LoopBack controller classes.
+ * Decorators apply REST api mapping metadata to controller classes and their
+ * members. And utilities that inspect controller classes to build OpenAPI 3.0.0
+ * specifications from REST API mapping metadata.
+ *
+ * Functions for more artifacts will be added when needed.
+ *
+ * @packageDocumentation
+ */
+
 export * from '@loopback/repository-json-schema';
 export * from './controller-spec';
 export * from './decorators';