Merge pull request nestjs#2688 from BrunnerLivio/feature/api-docs

docs() add API documentation

Author: kamilmysliwiec

packages/common/PACKAGE.md

@@ -0,0 +1 @@
+The common package comes with decorators such as `@Controller()`, `@Injectable` and so on.

packages/common/cache/cache.module.ts

@@ -8,18 +8,40 @@ import {
   CacheOptionsFactory,
 } from './interfaces/cache-module.interface';
 
+/**
+ * Module that provides Nest cache-manager.
+ *
+ * @see [Caching](https://docs.nestjs.com/techniques/caching)
+ *
+ * @publicApi
+ */
 @Module({
   providers: [createCacheManager()],
   exports: [CACHE_MANAGER],
 })
 export class CacheModule {
+  /**
+   * Configure the cache manager statically.
+   *
+   * @param options options to configure the cache manager
+   *
+   * @see [Customize caching](https://docs.nestjs.com/techniques/caching#customize-caching)
+   */
   static register(options: CacheModuleOptions = {}): DynamicModule {
     return {
       module: CacheModule,
       providers: [{ provide: CACHE_MODULE_OPTIONS, useValue: options }],
     };
   }
 
+  /**
+   * Configure the cache manager dynamically.
+   *
+   * @param options method for dynamically supplying cache manager configuration
+   * options
+   *
+   * @see [Async configuration](https://docs.nestjs.com/techniques/caching#async-configuration)
+   */
   static registerAsync(options: CacheModuleAsyncOptions): DynamicModule {
     return {
       module: CacheModule,

packages/common/cache/cache.providers.ts

@@ -4,6 +4,11 @@ import { CACHE_MANAGER, CACHE_MODULE_OPTIONS } from './cache.constants';
 import { defaultCacheOptions } from './default-options';
 import { CacheManagerOptions } from './interfaces/cache-manager.interface';
 
+/**
+ * Creates a CacheManager Provider.
+ *
+ * @publicApi
+ */
 export function createCacheManager(): Provider {
   return {
     provide: CACHE_MANAGER,

packages/common/cache/decorators/cache-key.decorator.ts

@@ -1,4 +1,17 @@
 import { SetMetadata } from '../../decorators';
 import { CACHE_KEY_METADATA } from '../cache.constants';
 
+/**
+ * Decorator that sets the caching key used to store/retrieve cached items for
+ * Web sockets or Microservice based apps.
+ *
+ * For example:
+ * `@CacheKey('events')`
+ *
+ * @param key string naming the field to be used as a cache key
+ *
+ * @see [Caching](https://docs.nestjs.com/techniques/caching)
+ *
+ * @publicApi
+ */
 export const CacheKey = (key: string) => SetMetadata(CACHE_KEY_METADATA, key);

packages/common/cache/interfaces/cache-manager.interface.ts

@@ -2,19 +2,70 @@ export interface LiteralObject {
   [key: string]: any;
 }
 
+/**
+ * Interface defining a cache store. Implement this interface to create a custom
+ * cache store.
+ *
+ * @publicApi
+ */
 export interface CacheStore {
+  /**
+   * Create a key/value pair in the cache.
+   *
+   * @param key cache key
+   * @param value cache value
+   */
   set<T>(key: string, value: T): Promise<void> | void;
+  /**
+   * Retrieve a key/value pair from the cache.
+   *
+   * @param key cache key
+   */
   get<T>(key: string): Promise<void> | void;
+  /**
+   * Destroy a key/value pair from the cache.
+   *
+   * @param key cache key
+   */
   del(key: string): void | Promise<void>;
 }
 
+/**
+ * Interface defining a factory to create a cache store.
+ *
+ * @publicApi
+ */
 export interface CacheStoreFactory {
+  /**
+   * Return a configured cache store.
+   *
+   * @param args Cache manager options received from `CacheModule.register()`
+   * or `CacheModule.registerAcync()`
+   */
   create(args: LiteralObject): CacheStore;
 }
 
+/**
+ * Interface defining Cache Manager configuration options.
+ *
+ * @publicApi
+ */
 export interface CacheManagerOptions {
+  /**
+   * Cache storage manager.  Default is `'memory'` (in-memory store).  See
+   * [Different stores](https://docs.nestjs.com/techniques/caching#different-stores)
+   * for more info.
+   */
   store?: string | CacheStoreFactory;
+  /**
+   * Time to live - amount of time in seconds that a response is cached before it
+   * is deleted. Subsequent request will call through the route handler and refresh
+   * the cache.  Defaults to 5 seconds.
+   */
   ttl?: number;
+  /**
+   * Maximum number of responses to store in the cache.  Defaults to 100.
+   */
   max?: number;
   isCacheableValue?: (value: any) => boolean;
 }

packages/common/cache/interfaces/cache-module.interface.ts

@@ -5,17 +5,47 @@ export interface CacheModuleOptions extends CacheManagerOptions {
   [key: string]: any;
 }
 
+/**
+ * Interface describing a `CacheOptionsFactory`.  Providers supplying configuration
+ * options for the Cache module must implement this interface.
+ *
+ * @see [Async configuration](https://docs.nestjs.com/techniques/caching#async-configuration)
+ *
+ * @publicApi
+ */
 export interface CacheOptionsFactory {
   createCacheOptions(): Promise<CacheModuleOptions> | CacheModuleOptions;
 }
 
+/**
+ * Options for dynamically configuring the Cache module.
+ *
+ * @see [Async configuration](https://docs.nestjs.com/techniques/caching#async-configuration)
+ *
+ * @publicApi
+ */
 export interface CacheModuleAsyncOptions
   extends Pick<ModuleMetadata, 'imports'> {
+  /**
+   * Injection token resolving to an existing provider. The provider must implement
+   * the `CacheOptionsFactory` interface.
+   */
   useExisting?: Type<CacheOptionsFactory>;
+  /**
+   * Injection token resolving to a class that will be instantiated as a provider.
+   * The class must implement the `CacheOptionsFactory` interface.
+   */
   useClass?: Type<CacheOptionsFactory>;
+  /**
+   * Function returning options (or a Promise resolving to options) to configure the
+   * cache module.
+   */
   useFactory?: (
     ...args: any[]
   ) => Promise<CacheModuleOptions> | CacheModuleOptions;
+  /**
+   * Dependencies that a Factory may inject.
+   */
   inject?: any[];
   extraProviders?: Provider[];
 }

packages/common/decorators/core/bind.decorator.ts

@@ -1,7 +1,12 @@
 /**
- * Binds parameter decorators to the method
- * Useful when the language doesn't provide a 'Parameter Decorators' feature (vanilla JavaScript)
- * @param  {} ...decorators
+ * Decorator that binds *parameter decorators* to the method that follows.
+ *
+ * Useful when the language doesn't provide a 'Parameter Decorator' feature
+ * (i.e., vanilla JavaScript).
+ *
+ * @param decorators one or more parameter decorators (e.g., `Req()`)
+ *
+ * @publicApi
  */
 export function Bind(...decorators: any[]): MethodDecorator {
   return <T>(

packages/common/decorators/core/catch.decorator.ts

@@ -2,8 +2,21 @@ import { FILTER_CATCH_EXCEPTIONS } from '../../constants';
 import { Type } from '../../interfaces';
 
 /**
- * Defines an exception filter. Takes set of exception types as arguments which have to be caught by this filter.
- * The class should implement the `ExceptionFilter` interface.
+ * Decorator that marks a class as a Nest exception filter. An exception filter
+ * handles exceptions thrown by or not handled by your application code.
+ *
+ * The decorated class must implement the `ExceptionFilter` interface.
+ *
+ * @param exceptions one or more exception *types* specifying
+ * the exceptions to be caught and handled by this filter.
+ *
+ * @see [Exception Filters](https://docs.nestjs.com/exception-filters)
+ *
+ * @usageNotes
+ * Exception filters are applied using the `@UseFilters()` decorator, or (globally)
+ * with `app.useGlobalFilters()`.
+ *
+ * @publicApi
  */
 export function Catch(...exceptions: Type<any>[]): ClassDecorator {
   return (target: object) => {

packages/common/decorators/core/controller.decorator.ts

@@ -2,26 +2,139 @@ import { PATH_METADATA, SCOPE_OPTIONS_METADATA } from '../../constants';
 import { isString, isUndefined } from '../../utils/shared.utils';
 import { ScopeOptions } from './../../interfaces/scope-options.interface';
 
+/**
+ * Interface defining options that can be passed to `@Controller()` decorator
+ *
+ * @publicApi
+ */
 export interface ControllerOptions extends ScopeOptions {
+  /**
+   * Specifies an optional `route path prefix`.  The prefix is pre-pended to the
+   * path specified in any request decorator in the class.
+   *
+   * @see [Routing](https://docs.nestjs.com/controllers#routing)
+   */
   path?: string;
 }
 
+export function Controller();
+export function Controller(prefix: string);
+export function Controller(options: ControllerOptions);
+/**
+ * Decorator that marks a class as a Nest controller that can receive inbound
+ * requests and produce responses.
+ *
+ * An HTTP Controller responds to inbound HTTP Requests and produces HTTP Responses.
+ * It defines a class that provides the context for one or more related route
+ * handlers that correspond to HTTP request methods and associated routes
+ * for example `GET /api/profile`, `POST /user/resume`.
+ *
+ * A Microservice Controller responds to requests as well as events, running over
+ * a variety of transports [(read more here)](https://docs.nestjs.com/microservices/basics).
+ * It defines a class that provides a context for one or more message or event
+ * handlers.
+ *
+ * @see [Controllers](https://docs.nestjs.com/controllers)
+ * @see [Microservices](https://docs.nestjs.com/microservices/basics#request-response)
+ *
+ * @publicApi
+ */
+export function Controller();
+
+/**
+ * Decorator that marks a class as a Nest controller that can receive inbound
+ * requests and produce responses.
+ *
+ * An HTTP Controller responds to inbound HTTP Requests and produces HTTP Responses.
+ * It defines a class that provides the context for one or more related route
+ * handlers that correspond to HTTP request methods and associated routes
+ * for example `GET /api/profile`, `POST /user/resume`.
+ *
+ * A Microservice Controller responds to requests as well as events, running over
+ * a variety of transports [(read more here)](https://docs.nestjs.com/microservices/basics).
+ * It defines a class that provides a context for one or more message or event
+ * handlers.
+ *
+ * @param {string} prefix string that defines a `route path prefix`.  The prefix
+ * is pre-pended to the path specified in any request decorator in the class.
+ *
+ * @see [Routing](https://docs.nestjs.com/controllers#routing)
+ * @see [Controllers](https://docs.nestjs.com/controllers)
+ * @see [Microservices](https://docs.nestjs.com/microservices/basics#request-response)
+ *
+ * @publicApi
+ */
+export function Controller(prefix: string);
+
+/**
+ * Decorator that marks a class as a Nest controller that can receive inbound
+ * requests and produce responses.
+ *
+ * An HTTP Controller responds to inbound HTTP Requests and produces HTTP Responses.
+ * It defines a class that provides the context for one or more related route
+ * handlers that correspond to HTTP request methods and associated routes
+ * for example `GET /api/profile`, `POST /user/resume`.
+ *
+ * A Microservice Controller responds to requests as well as events, running over
+ * a variety of transports [(read more here)](https://docs.nestjs.com/microservices/basics).
+ * It defines a class that provides a context for one or more message or event
+ * handlers.
+ *
+ * @param {object} options configuration object specifying:
+ *
+ * - `scope` - symbol that determines the lifetime of a Controller instance.
+ * [See Scope](https://docs.nestjs.com/fundamentals/injection-scopes#usage) for
+ * more details.
+ * - `prefix` - string that defines a `route path prefix`.  The prefix
+ * is pre-pended to the path specified in any request decorator in the class.
+ *
+ * @see [Routing](https://docs.nestjs.com/controllers#routing)
+ * @see [Controllers](https://docs.nestjs.com/controllers)
+ * @see [Microservices](https://docs.nestjs.com/microservices/basics#request-response)
+ *
+ * @publicApi
+ */
+export function Controller(options: ControllerOptions);
+
 /**
- * Defines the controller. Controller can inject dependencies through constructor.
- * Those dependencies have to belong to the same module.
+ * Decorator that marks a class as a Nest controller that can receive inbound
+ * requests and produce responses.
+ *
+ * An HTTP Controller responds to inbound HTTP Requests and produces HTTP Responses.
+ * It defines a class that provides the context for one or more related route
+ * handlers that correspond to HTTP request methods and associated routes
+ * for example `GET /api/profile`, `POST /user/resume`
+ *
+ * A Microservice Controller responds to requests as well as events, running over
+ * a variety of transports [(read more here)](https://docs.nestjs.com/microservices/basics).
+ * It defines a class that provides a context for one or more message or event
+ * handlers.
+ *
+ * @param prefixOrOptions a `route path prefix` or a `ControllerOptions` object.
+ * A `route path prefix` is pre-pended to the path specified in any request decorator
+ * in the class. `ControllerOptions` is an options configuration object specifying:
+ * - `scope` - symbol that determines the lifetime of a Controller instance.
+ * [See Scope](https://docs.nestjs.com/fundamentals/injection-scopes#usage) for
+ * more details.
+ * - `prefix` - string that defines a `route path prefix`.  The prefix
+ * is pre-pended to the path specified in any request decorator in the class.
+ *
+ * @see [Routing](https://docs.nestjs.com/controllers#routing)
+ * @see [Controllers](https://docs.nestjs.com/controllers)
+ * @see [Microservices](https://docs.nestjs.com/microservices/basics#request-response)
+ * @see [Scope](https://docs.nestjs.com/fundamentals/injection-scopes#usage)
+ *
+ * @publicApi
  */
-export function Controller(): ClassDecorator;
-export function Controller(prefix: string): ClassDecorator;
-export function Controller(options: ControllerOptions): ClassDecorator;
 export function Controller(
   prefixOrOptions?: string | ControllerOptions,
 ): ClassDecorator {
   const defaultPath = '/';
   const [path, scopeOptions] = isUndefined(prefixOrOptions)
     ? [defaultPath, undefined]
     : isString(prefixOrOptions)
-      ? [prefixOrOptions, undefined]
-      : [prefixOrOptions.path || defaultPath, { scope: prefixOrOptions.scope }];
+    ? [prefixOrOptions, undefined]
+    : [prefixOrOptions.path || defaultPath, { scope: prefixOrOptions.scope }];
 
   return (target: object) => {
     Reflect.defineMetadata(PATH_METADATA, path, target);