Add js docs for Authentication package

packages/authentication/src/decorator.ts

@@ -6,17 +6,19 @@
 import {Reflector, Constructor} from '@loopback/context';
 import {BindingKeys} from './keys';
 
-/* class to hold authentication metadata
+/**
+ * Authentication metadata stored via Reflection API
  */
 export interface AuthenticationMetadata {
   strategy: string;
   options?: Object;
 }
 
 /**
- * decorator to add authentication metadata to controller methods
- * @param strategyName
- * @param options
+ * 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.
  */
 export function authenticate(strategyName: string, options?: Object) {
   return function(controllerClass: Object, methodName: string) {
@@ -34,9 +36,10 @@ export function authenticate(strategyName: string, options?: Object) {
 }
 
 /**
- * function to get stored authentication metadata in a controller method
- * @param controllerObj
- * @param methodName
+ * Fetch authentication metadata stored by `@authenticate` decorator.
+ *
+ * @param controllerClass Target controller
+ * @param methodName Target method
  */
 export function getAuthenticateMetadata(
   controllerClass: Constructor<{}>,

packages/authentication/src/keys.ts

@@ -3,6 +3,9 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+/**
+ * Binding keys used by this component.
+ */
 export namespace BindingKeys {
   export namespace Authentication {
     export const STRATEGY = 'authentication.strategy';

packages/context/src/binding.ts

@@ -286,7 +286,20 @@ export class Binding {
   }
 
   /**
-   * Bind the key to a BindingProvider
+   * Bind the key to a value computed by a Provider.
+   *
+   * * @example
+   *
+   * ```ts
+   * export class DateProvider implements Provider<Date> {
+   *   constructor(@inject('stringDate') private param: String){}
+   *   value(): Date {
+   *     return new Date(param);
+   *   }
+   * }
+   * ```
+   *
+   * @param provider The value provider to use.
    */
   public toProvider<T>(providerClass: Constructor<Provider<T>>): this {
     this._getValue = ctx => {

packages/context/src/provider.ts

@@ -6,32 +6,32 @@
 import {ValueOrPromise} from './binding';
 
 /**
- * @exports Provider<T> : interface definition for a provider of a value
- * of type T
- * @summary Providers allow binding of a value provider class instead of the
- * value itself
- * @example:
+ * Providers allow developers to compute injected values dynamically,
+ * with any dependencies required by the value getter injected automatically
+ * from the Context.
+ *
+ * @example
+ *
  * ```ts
  * export class DateProvider implements Provider<Date> {
  *   constructor(@inject('stringDate') private param: String){}
  *   value(): Date {
  *     return new Date(param);
  *   }
  * }
- * ```
- * @example: Binding a context
- * ```ts
+ *
+ * ctx.bind('stringDate').to('2017-01-01')
  * ctx.bind('provider_key').toProvider(MyProvider);
- * ```
- * @example: getting a value dynamically
- * ```ts
- * ctx.get('provider_key');
- * ctx.getBinding('provider_key').getValue();
+ *
+ * const value = ctx.getAsync('provider_key');
+ * // value is a Date instance
  * ```
  */
 export interface Provider<T> {
   /**
-   * @returns a value or a promise
+   * @returns The value to inject to dependents.
+   * This method can return a promise too, in which case the IoC framework
+   * will resolve this promise to obtain the value to inject.
    */
   value(): ValueOrPromise<T>;
 }