chore: update @param tsdoc comments to use the official format

Normalize `@param name description` to be `@param name - description` See microsoft/tsdoc#128
loopbackio · May 21, 2019 · d1646d0 · d1646d0
1 parent f1da3fe
commit d1646d0
Show file tree

Hide file tree

Showing 121 changed files with 909 additions and 909 deletions.
diff --git a/docs/site/Context.md b/docs/site/Context.md
@@ -300,9 +300,9 @@ To make it easy to support asynchronous event processing, we introduce
 ```ts
 /**
  * Listen on `bind`, `unbind`, or other events
- * @param eventType Context event type
- * @param binding The binding as event source
- * @param context Context object for the binding event
+ * @param eventType - Context event type
+ * @param binding - The binding as event source
+ * @param context - Context object for the binding event
  */
 export type ContextObserverFn = (
   eventType: ContextEventType,
@@ -322,8 +322,8 @@ export interface ContextObserver {
 
   /**
    * Listen on `bind`, `unbind`, or other events
-   * @param eventType Context event type
-   * @param binding The binding as event source
+   * @param eventType - Context event type
+   * @param binding - The binding as event source
    */
   observe: ContextObserverFn;
 }

diff --git a/docs/site/Extending-request-body-parsing.md b/docs/site/Extending-request-body-parsing.md
@@ -43,12 +43,12 @@ export interface BodyParser {
   name: string | symbol;
   /**
    * Indicate if the given media type is supported
-   * @param mediaType Media type
+   * @param mediaType - Media type
    */
   supports(mediaType: string): boolean;
   /**
    * Parse the request body
-   * @param request http request
+   * @param request - http request
    */
   parse(request: Request): Promise<RequestBody>;
 }

diff --git a/docs/site/Interceptors.md b/docs/site/Interceptors.md
@@ -469,8 +469,8 @@ parameters:
  */
 export interface Interceptor {
   /**
-   * @param context Invocation context
-   * @param next A function to invoke next interceptor or the target method
+   * @param context - Invocation context
+   * @param next - A function to invoke next interceptor or the target method
    * @returns A result as value or promise
    */
   (
@@ -513,11 +513,11 @@ bindings. It extends `Context` with additional properties as follows:
 export class InvocationContext extends Context {
   /**
    * Construct a new instance
-   * @param parent Parent context, such as the RequestContext
-   * @param target Target class (for static methods) or prototype/object
+   * @param parent - Parent context, such as the RequestContext
+   * @param target - Target class (for static methods) or prototype/object
    * (for instance methods)
-   * @param methodName Method name
-   * @param args An array of arguments
+   * @param methodName - Method name
+   * @param args - An array of arguments
    */
   constructor(
     parent: Context,

diff --git a/docs/site/Routing-requests.md b/docs/site/Routing-requests.md
@@ -68,13 +68,13 @@ below:
 export interface RestRouter {
   /**
    * Add a route to the router
-   * @param route A route entry
+   * @param route - A route entry
    */
   add(route: RouteEntry): boolean;
 
   /**
    * Find a matching route for the given http request
-   * @param request Http request
+   * @param request - Http request
    * @returns The resolved route, if not found, `undefined` is returned
    */
   find(request: Request): ResolvedRoute | undefined;

diff --git a/docs/site/Sequence.md b/docs/site/Sequence.md
@@ -157,8 +157,8 @@ export class CustomSendProvider implements Provider<Send> {
   /**
    * Use the mimeType given in the request's Accept header to convert
    * the response object!
-   * @param response The response object used to reply to the  client.
-   * @param result The result of the operation carried out by the controller's
+   * @param response - The response object used to reply to the  client.
+   * @param result - The result of the operation carried out by the controller's
    * handling function.
    */
   action(response: Response, result: OperationRetval) {

diff --git a/examples/greeter-extension/README.md b/examples/greeter-extension/README.md
@@ -126,7 +126,7 @@ export class GreetingService {
   // ...
   /**
    * Find a greeter that can speak the given language
-   * @param language Language code for the greeting
+   * @param language - Language code for the greeting
    */
   async findGreeter(language: string): Promise<Greeter | undefined> {
     // Get the latest list of greeters
@@ -137,8 +137,8 @@ export class GreetingService {
 
   /**
    * Greet in the given language
-   * @param language Language code
-   * @param name Name
+   * @param language - Language code
+   * @param name - Name
    */
   async greet(language: string, name: string): Promise<string> {
     let greeting: string = '';

diff --git a/examples/greeter-extension/src/greeting-service.ts b/examples/greeter-extension/src/greeting-service.ts
@@ -38,7 +38,7 @@ export class GreetingService {
 
   /**
    * Find a greeter that can speak the given language
-   * @param language Language code for the greeting
+   * @param language - Language code for the greeting
    */
   async findGreeter(language: string): Promise<Greeter | undefined> {
     // Get the latest list of greeters
@@ -49,8 +49,8 @@ export class GreetingService {
 
   /**
    * Greet in the given language
-   * @param language Language code
-   * @param name Name
+   * @param language - Language code
+   * @param name - Name
    */
   async greet(language: string, name: string): Promise<string> {
     let greeting: string = '';

diff --git a/examples/log-extension/README.md b/examples/log-extension/README.md
@@ -185,7 +185,7 @@ import {LevelMetadata} from '../types';
  * if it is set at or greater than Application LogLevel.
  * LOG_LEVEL.DEBUG < LOG_LEVEL.INFO < LOG_LEVEL.WARN < LOG_LEVEL.ERROR < LOG_LEVEL.OFF
  *
- * @param level The Log Level at or above it should log
+ * @param level - The Log Level at or above it should log
  */
 export function log(level?: number) {
   if (level === undefined) level = LOG_LEVEL.WARN;
@@ -200,8 +200,8 @@ export function log(level?: number) {
 /**
  * Fetch log level stored by `@log` decorator.
  *
- * @param controllerClass Target controller
- * @param methodName Target method
+ * @param controllerClass - Target controller
+ * @param methodName - Target method
  */
 export function getLogMetadata(
   controllerClass: Constructor<{}>,

diff --git a/examples/log-extension/src/decorators/log.decorator.ts b/examples/log-extension/src/decorators/log.decorator.ts
@@ -16,7 +16,7 @@ import {LevelMetadata} from '../types';
  * if it is set at or greater than Application LogLevel.
  * LOG_LEVEL.DEBUG < LOG_LEVEL.INFO < LOG_LEVEL.WARN < LOG_LEVEL.ERROR < LOG_LEVEL.OFF
  *
- * @param level The Log Level at or above it should log
+ * @param level - The Log Level at or above it should log
  */
 export function log(level?: number) {
   if (level === undefined) level = LOG_LEVEL.WARN;
@@ -31,8 +31,8 @@ export function log(level?: number) {
 /**
  * Fetch log level stored by `@log` decorator.
  *
- * @param controllerClass Target controller
- * @param methodName Target method
+ * @param controllerClass - Target controller
+ * @param methodName - Target method
  */
 export function getLogMetadata(
   controllerClass: Constructor<{}>,

diff --git a/examples/log-extension/src/mixins/log.mixin.ts b/examples/log-extension/src/mixins/log.mixin.ts
@@ -33,7 +33,7 @@ export function LogMixin<T extends Constructor<any>>(superClass: T) {
     /**
      * Set minimum logLevel to be displayed.
      *
-     * @param level The log level to set for @log decorator
+     * @param level - The log level to set for @log decorator
      *
      * @example
      * ```ts

diff --git a/examples/todo-list/src/__tests__/helpers.ts b/examples/todo-list/src/__tests__/helpers.ts
@@ -27,7 +27,7 @@ import {Todo, TodoList, TodoListImage} from '../models';
 
 /**
  * Generate a complete Todo object for use with tests.
- * @param todo A partial (or complete) Todo object.
+ * @param todo - A partial (or complete) Todo object.
  */
 export function givenTodo(todo?: Partial<Todo>) {
   const data = Object.assign(
@@ -44,7 +44,7 @@ export function givenTodo(todo?: Partial<Todo>) {
 
 /**
  * Generate a complete TodoList object for use with tests
- * @param todoList A partial (or complete) TodoList object.
+ * @param todoList - A partial (or complete) TodoList object.
  */
 export function givenTodoList(todoList?: Partial<TodoList>) {
   const data = Object.assign(
@@ -58,7 +58,7 @@ export function givenTodoList(todoList?: Partial<TodoList>) {
 
 /**
  * Generate a complete TodoListImage object for use with tests.
- * @param todoListImage A partial (or complete) TodoListImage object.
+ * @param todoListImage - A partial (or complete) TodoListImage object.
  */
 export function givenTodoListImage(todoListImage?: Partial<TodoListImage>) {
   const data = Object.assign(

diff --git a/examples/todo/src/__tests__/helpers.ts b/examples/todo/src/__tests__/helpers.ts
@@ -32,7 +32,7 @@ import * as GEO_CODER_CONFIG from '../datasources/geocoder.datasource.json';
 
 /**
  * Generate a complete Todo object for use with tests.
- * @param todo A partial (or complete) Todo object.
+ * @param todo - A partial (or complete) Todo object.
  */
 export function givenTodo(todo?: Partial<Todo>) {
   const data = Object.assign(

diff --git a/packages/authentication/src/decorators/authenticate.decorator.ts b/packages/authentication/src/decorators/authenticate.decorator.ts
@@ -21,8 +21,8 @@ export interface AuthenticationMetadata {
 /**
  * Mark a controller method as requiring authenticated user.
  *
- * @param strategyName The name of the authentication strategy to use.
- * @param options Additional options to configure the authentication.
+ * @param strategyName - The name of the authentication strategy to use.
+ * @param options - Additional options to configure the authentication.
  */
 export function authenticate(strategyName: string, options?: Object) {
   return MethodDecoratorFactory.createDecorator<AuthenticationMetadata>(
@@ -37,8 +37,8 @@ export function authenticate(strategyName: string, options?: Object) {
 /**
  * Fetch authentication metadata stored by `@authenticate` decorator.
  *
- * @param controllerClass Target controller
- * @param methodName Target method
+ * @param controllerClass - Target controller
+ * @param methodName - Target method
  */
 export function getAuthenticateMetadata(
   controllerClass: Constructor<{}>,

diff --git a/packages/authentication/src/providers/auth-action.provider.ts b/packages/authentication/src/providers/auth-action.provider.ts
@@ -40,7 +40,7 @@ export class AuthenticateActionProvider implements Provider<AuthenticateFn> {
 
   /**
    * The implementation of authenticate() sequence action.
-   * @param request The incoming request provided by the REST layer
+   * @param request - The incoming request provided by the REST layer
    */
   async action(request: Request): Promise<UserProfile | undefined> {
     const strategy = await this.getStrategy();

diff --git a/packages/authentication/src/services/user.service.ts b/packages/authentication/src/services/user.service.ts
@@ -84,15 +84,15 @@ export interface UserService<U, C> {
    *   }
    * };
    * ```
-   * @param credentials Credentials for basic auth or configurations for 3rd party.
+   * @param credentials - Credentials for basic auth or configurations for 3rd party.
    *                    Example see the
    */
   verifyCredentials(credentials: C): Promise<U>;
 
   /**
    * Convert the user returned by `verifyCredentials()` to a common
    * user profile that describes a user in your application
-   * @param user The user returned from `verifyCredentials()`
+   * @param user - The user returned from `verifyCredentials()`
    */
   convertToUserProfile(user: U): UserProfile;
 }
diff --git a/packages/authentication/src/strategy-adapter.ts b/packages/authentication/src/strategy-adapter.ts
@@ -25,7 +25,7 @@ const passportRequestMixin = require('passport/lib/http/request');
  */
 export class StrategyAdapter {
   /**
-   * @param strategy instance of a class which implements a passport-strategy;
+   * @param strategy - instance of a class which implements a passport-strategy;
    * @description http://passportjs.org/
    */
   constructor(private readonly strategy: Strategy) {}
@@ -35,7 +35,7 @@ export class StrategyAdapter {
    *     1. Create an instance of the strategy
    *     2. add success and failure state handlers
    *     3. authenticate using the strategy
-   * @param request The incoming request.
+   * @param request - The incoming request.
    */
   authenticate(request: Request): Promise<UserProfile> {
     return new Promise<UserProfile>((resolve, reject) => {

diff --git a/packages/boot/src/boot.component.ts b/packages/boot/src/boot.component.ts
@@ -35,7 +35,7 @@ export class BootComponent implements Component {
 
   /**
    *
-   * @param app Application instance
+   * @param app - Application instance
    */
   constructor(@inject(CoreBindings.APPLICATION_INSTANCE) app: Application) {
     // Bound as a SINGLETON so it can be cached as it has no state

diff --git a/packages/boot/src/booters/application-metadata.booter.ts b/packages/boot/src/booters/application-metadata.booter.ts
@@ -16,8 +16,8 @@ const debug = debugModule('loopback:boot:booter:application-metadata');
  *
  * Configure the application with metadata from `package.json`
  *
- * @param app Application instance
- * @param projectRoot Root of User Project
+ * @param app - Application instance
+ * @param projectRoot - Root of User Project
  */
 export class ApplicationMetadataBooter implements Booter {
   constructor(

diff --git a/packages/boot/src/booters/booter-utils.ts b/packages/boot/src/booters/booter-utils.ts
@@ -14,8 +14,8 @@ const debug = debugFactory('loopback:boot:booter-utils');
 /**
  * Returns all files matching the given glob pattern relative to root
  *
- * @param pattern A glob pattern
- * @param root Root folder to start searching for matching files
+ * @param pattern - A glob pattern
+ * @param root - Root folder to start searching for matching files
  * @returns {string[]} Array of discovered files
  */
 export async function discoverFiles(
@@ -28,7 +28,7 @@ export async function discoverFiles(
 /**
  * Given a function, returns true if it is a class, false otherwise.
  *
- * @param target The function to check if it's a class or not.
+ * @param target - The function to check if it's a class or not.
  * @returns {boolean} True if target is a class. False otherwise.
  */
 // tslint:disable-next-line:no-any
@@ -43,8 +43,8 @@ export function isClass(target: any): target is Constructor<any> {
  * identifying the exports from the file by getting the keys of the file
  * and then testing each exported member to see if it's a class or not.
  *
- * @param files An array of string of absolute file paths
- * @param projectRootDir The project root directory
+ * @param files - An array of string of absolute file paths
+ * @param projectRootDir - The project root directory
  * @returns {Constructor<{}>[]} An array of Class constructors from a file
  */
 export function loadClassesFromFiles(

diff --git a/packages/boot/src/booters/controller.booter.ts b/packages/boot/src/booters/controller.booter.ts
@@ -15,9 +15,9 @@ import {BootBindings} from '../keys';
  *
  * Supported phases: configure, discover, load
  *
- * @param app Application instance
- * @param projectRoot Root of User Project relative to which all paths are resolved
- * @param [bootConfig] Controller Artifact Options Object
+ * @param app - Application instance
+ * @param projectRoot - Root of User Project relative to which all paths are resolved
+ * @param bootConfig - Controller Artifact Options Object
  */
 export class ControllerBooter extends BaseArtifactBooter {
   constructor(

diff --git a/packages/boot/src/booters/datasource.booter.ts b/packages/boot/src/booters/datasource.booter.ts
@@ -20,9 +20,9 @@ import {BootBindings} from '../keys';
  *
  * Supported phases: configure, discover, load
  *
- * @param app Application instance
- * @param projectRoot Root of User Project relative to which all paths are resolved
- * @param [bootConfig] DataSource Artifact Options Object
+ * @param app - Application instance
+ * @param projectRoot - Root of User Project relative to which all paths are resolved
+ * @param bootConfig - DataSource Artifact Options Object
  */
 export class DataSourceBooter extends BaseArtifactBooter {
   constructor(

diff --git a/packages/boot/src/booters/lifecyle-observer.booter.ts b/packages/boot/src/booters/lifecyle-observer.booter.ts
@@ -24,9 +24,9 @@ type LifeCycleObserverClass = Constructor<LifeCycleObserver>;
  *
  * Supported phases: configure, discover, load
  *
- * @param app Application instance
- * @param projectRoot Root of User Project relative to which all paths are resolved
- * @param [bootConfig] LifeCycleObserver Artifact Options Object
+ * @param app - Application instance
+ * @param projectRoot - Root of User Project relative to which all paths are resolved
+ * @param bootConfig - LifeCycleObserver Artifact Options Object
  */
 export class LifeCycleObserverBooter extends BaseArtifactBooter {
   observers: LifeCycleObserverClass[];

diff --git a/packages/boot/src/booters/repository.booter.ts b/packages/boot/src/booters/repository.booter.ts
@@ -17,9 +17,9 @@ import {ArtifactOptions} from '../interfaces';
  *
  * Supported phases: configure, discover, load
  *
- * @param app Application instance
- * @param projectRoot Root of User Project relative to which all paths are resolved
- * @param [bootConfig] Repository Artifact Options Object
+ * @param app - Application instance
+ * @param projectRoot - Root of User Project relative to which all paths are resolved
+ * @param bootConfig - Repository Artifact Options Object
  */
 export class RepositoryBooter extends BaseArtifactBooter {
   constructor(