chore: fix tsdoc comments for @example

Embedded typescript code in comments cannot be rendered correctly inside
markdown tables. Add @example to extract example code snippets.

examples/log-extension/src/mixins/log.mixin.ts

@@ -12,6 +12,7 @@ import {LogComponent} from '../component';
  * Also provides .logLevel() to bind application wide logLevel.
  * Functions with a log level set to logLevel or higher sill log data
  *
+ * @example
  * ```ts
  * class MyApplication extends LogMixin(Application) {}
  * ```
@@ -34,6 +35,7 @@ export function LogMixin<T extends Constructor<any>>(superClass: T) {
      *
      * @param level The log level to set for @log decorator
      *
+     * @example
      * ```ts
      * app.logLevel(LOG_LEVEL.INFO);
      * ```

packages/authentication/src/keys.ts

@@ -16,6 +16,7 @@ export namespace AuthenticationBindings {
    * Key used to bind an authentication strategy to the context for the
    * authentication function to use.
    *
+   * @example
    * ```ts
    * server
    *   .bind(AuthenticationBindings.STRATEGY)
@@ -29,6 +30,7 @@ export namespace AuthenticationBindings {
   /**
    * Key used to inject the authentication function into the sequence.
    *
+   * @example
    * ```ts
    * class MySequence implements SequenceHandler {
    *   constructor(
@@ -64,6 +66,7 @@ export namespace AuthenticationBindings {
    * Key used to inject authentication metadata, which is used to determine
    * whether a request requires authentication or not.
    *
+   * @example
    * ```ts
    * class MyPassportStrategyProvider implements Provider<Strategy | undefined> {
    *   constructor(
@@ -86,6 +89,8 @@ export namespace AuthenticationBindings {
   /**
    * Key used to inject the user instance retrieved by the
    * authentication function
+   *
+   * @example
    * ```ts
    * class MyController {
    *   constructor(

packages/authentication/src/services/user.service.ts

@@ -55,6 +55,7 @@ export interface UserService<U, C> {
    * Verify the identity of a user, construct a corresponding user profile using
    * the user information and return the user profile.
    *
+   * @example
    * A pseudo code for basic authentication:
    * ```ts
    * verifyCredentials(credentials: C): Promise<U> {

packages/boot/src/mixins/boot.mixin.ts

@@ -79,6 +79,7 @@ export function BootMixin<T extends Constructor<any>>(superClass: T) {
      *
      * @param booterCls Booter classes to bind to the Application
      *
+     * @example
      * ```ts
      * app.booters(MyBooter, MyOtherBooter)
      * ```
@@ -94,6 +95,7 @@ export function BootMixin<T extends Constructor<any>>(superClass: T) {
      *
      * @param component The component to add.
      *
+     * @example
      * ```ts
      *
      * export class ProductComponent {

packages/context/src/binding-filter.ts

@@ -10,6 +10,7 @@ import {BindingAddress} from './binding-key';
  * A function that filters bindings. It returns `true` to select a given
  * binding.
  *
+ * @remarks
  * TODO(semver-major): We might change this type in the future to either remove
  * the `<ValueType>` or make it as type guard by asserting the matched binding
  * to be typed with `<ValueType>`.

packages/context/src/binding-inspector.ts

@@ -155,7 +155,9 @@ export function bindingTemplateFor<T = unknown>(
 }
 
 /**
- * Mapping artifact types to binding key namespaces (prefixes). For example:
+ * Mapping artifact types to binding key namespaces (prefixes).
+ *
+ * @example
  * ```ts
  * {
  *   repository: 'repositories'

packages/context/src/binding-key.ts

@@ -12,7 +12,7 @@ export class BindingKey<ValueType> {
   /**
    * Create a new key for a binding bound to a value of type `ValueType`.
    *
-   * **Example**
+   * @example
    *
    * ```ts
    * BindingKey.create<string>('application.name');

packages/context/src/binding.ts

@@ -233,9 +233,10 @@ export class Binding<T = BoundValue> {
    *  - the bound value
    *  - a promise of the bound value
    *
-   * Consumers wishing to consume sync values directly should use `isPromise`
+   * Consumers wishing to consume sync values directly should use `isPromiseLike`
    * to check the type of the returned value to decide how to handle it.
    *
+   * @example
    * ```
    * const result = binding.getValue(ctx);
    * if (isPromiseLike(result)) {
@@ -540,7 +541,7 @@ export class Binding<T = BoundValue> {
    * Apply one or more template functions to set up the binding with scope,
    * tags, and other attributes as a group.
    *
-   * For example,
+   * @example
    * ```ts
    * const serverTemplate = (binding: Binding) =>
    *   binding.inScope(BindingScope.SINGLETON).tag('server');

packages/context/src/context.ts

@@ -97,7 +97,9 @@ export class Context extends EventEmitter {
   private notificationQueue: AsyncIterableIterator<Notification> | undefined;
 
   /**
-   * Create a new context. For example,
+   * Create a new context.
+   *
+   * @example
    * ```ts
    * // Create a new root context, let the framework to create a unique name
    * const rootCtx = new Context();
@@ -354,12 +356,15 @@ export class Context extends EventEmitter {
   }
 
   /**
-   * Unbind a binding from the context. No parent contexts will be checked. If
-   * you need to unbind a binding owned by a parent context, use the code below:
+   * Unbind a binding from the context. No parent contexts will be checked.
+   *
+   * @remarks
+   * If you need to unbind a binding owned by a parent context, use the code below:
    * ```ts
    * const ownerCtx = ctx.getOwnerContext(key);
    * return ownerCtx != null && ownerCtx.unbind(key);
    * ```
+   *
    * @param key Binding key
    * @returns true if the binding key is found and removed from this context
    */

packages/context/src/inject.ts

@@ -81,6 +81,7 @@ export interface Injection<ValueType = BoundValue> {
  * A decorator to annotate method arguments for automatic injection
  * by LoopBack IoC container.
  *
+ * @example
  * Usage - Typescript:
  *
  * ```ts
@@ -206,7 +207,7 @@ export namespace Getter {
  * The function injected by `@inject.setter(bindingKey)`. It sets the underlying
  * binding to a constant value using `binding.to(value)`.
  *
- * For example:
+ * @example
  *
  * ```ts
  * setterFn('my-value');
@@ -282,7 +283,7 @@ export namespace inject {
    * `metadata.bindingCreation` option. See `BindingCreationPolicy` for more
    * details.
    *
-   * For example:
+   * @example
    *
    * ```ts
    * class MyAuthAction {
@@ -311,7 +312,7 @@ export namespace inject {
   /**
    * Inject an array of values by a tag pattern string or regexp
    *
-   * For example,
+   * @example
    * ```ts
    * class AuthenticationManager {
    *   constructor(
@@ -336,6 +337,7 @@ export namespace inject {
   /**
    * Inject matching bound values by the filter function
    *
+   * @example
    * ```ts
    * class MyControllerWithView {
    *   @inject.view(filterByTag('foo'))

packages/core/src/application.ts

@@ -51,6 +51,7 @@ export class Application extends Context implements LifeCycleObserver {
    * further modify the binding, e.g. lock the value to prevent further
    * modifications.
    *
+   * @example
    * ```ts
    * class MyController {
    * }
@@ -74,6 +75,7 @@ export class Application extends Context implements LifeCycleObserver {
    * Each server constructor added in this way must provide a unique prefix
    * to prevent binding overlap.
    *
+   * @example
    * ```ts
    * app.server(RestServer);
    * // This server constructor will be bound under "servers.RestServer".
@@ -107,6 +109,7 @@ export class Application extends Context implements LifeCycleObserver {
    * Each server added in this way will automatically be named based on the
    * class constructor name with the "servers." prefix.
    *
+   * @remarks
    * If you wish to control the binding keys for particular server instances,
    * use the app.server function instead.
    * ```ts
@@ -181,6 +184,7 @@ export class Application extends Context implements LifeCycleObserver {
    * @param componentCtor The component class to add.
    * @param {string=} name Optional component name, default to the class name
    *
+   * @example
    * ```ts
    *
    * export class ProductComponent {

packages/core/src/component.ts

@@ -40,7 +40,8 @@ export interface Component {
 
   /**
    * A map of providers to be bound to the application context
-   * * For example:
+   *
+   * @example
    * ```ts
    * {
    *   'authentication.strategies.ldap': LdapStrategyProvider
@@ -52,7 +53,7 @@ export interface Component {
   /**
    * A map of classes to be bound to the application context.
    *
-   * For example:
+   * @example
    * ```ts
    * {
    *   'rest.body-parsers.xml': XmlBodyParser
@@ -71,7 +72,9 @@ export interface Component {
   lifeCycleObservers?: Constructor<LifeCycleObserver>[];
 
   /**
-   * An array of bindings to be aded to the application context. For example,
+   * An array of bindings to be aded to the application context.
+   *
+   * @example
    * ```ts
    * const bindingX = Binding.bind('x').to('Value X');
    * this.bindings = [bindingX]

packages/core/src/extension-point.ts

@@ -21,8 +21,9 @@ import {CoreTags} from './keys';
 
 /**
  * Decorate a class as a named extension point. If the decoration is not
- * present, the name of the class will be used. For example:
+ * present, the name of the class will be used.
  *
+ * @example
  * ```ts
  * import {extensionPoint} from '@loopback/core';
  *
@@ -39,8 +40,9 @@ export function extensionPoint(name: string, ...specs: BindingSpec[]) {
 }
 
 /**
- * Shortcut to inject extensions for the given extension point. For example:
+ * Shortcut to inject extensions for the given extension point.
  *
+ * @example
  * ```ts
  * import {Getter} from '@loopback/context';
  * import {extensionPoint, extensions} from '@loopback/core';

packages/metadata/src/decorator-factory.ts

@@ -623,8 +623,11 @@ export class ParameterDecoratorFactory<T> extends DecoratorFactory<
 }
 
 /**
- * Factory for method level parameter decorator. For example, the following
- * code uses `@param` to declare two parameters for `greet()`.
+ * Factory for method level parameter decorator.
+ *
+ * @example
+ * For example, the following code uses `@param` to declare two parameters for
+ * `greet()`.
  * ```ts
  * class MyController {
  *   @param('name') // Parameter 0

packages/openapi-v3/src/decorators/parameter.decorator.ts

@@ -103,7 +103,9 @@ const builtinTypes = {
  * takes an argument of `ParameterObject` to define how to map the parameter
  * to OpenAPI specification.
  *
- * `@param(paramSpec)` must be applied to parameters. For example,
+ * `@param(paramSpec)` must be applied to parameters.
+ *
+ * @example
  * ```ts
  * class MyController {
  *   @get('/')

packages/openapi-v3/src/decorators/request-body.decorator.ts

@@ -23,6 +23,7 @@ export const REQUEST_BODY_INDEX = 'x-parameter-index';
  * A typical OpenAPI requestBody spec contains property
  * `description`, `required`, and `content`:
  *
+ * @example
  * ```ts
  * requestBodySpec: {
  *   description: 'a user',

packages/repository/src/common-types.ts

@@ -19,8 +19,10 @@ export interface Class<T> {
 }
 
 /**
- * Interface for constructor functions without `new` operator, for example,
- * ```
+ * Interface for constructor functions without `new` operator.
+ *
+ * @example
+ * ```ts
  * function Foo(x) {
  *   if (!(this instanceof Foo)) { return new Foo(x); }
  *   this.x = x;

packages/repository/src/decorators/repository.decorator.ts

@@ -85,6 +85,7 @@ export class RepositoryMetadata {
 /**
  * Decorator for repository injections on properties or method arguments
  *
+ * @example
  * ```ts
  * class CustomerController {
  *   @repository(CustomerRepository) public custRepo: CustomerRepository;
@@ -106,6 +107,7 @@ export function repository(
  * Decorator for DefaultCrudRepository generation and injection on properties
  * or method arguments based on the given model and dataSource (or their names)
  *
+ * @example
  * ```ts
  * class CustomerController {
  *   @repository('Customer', 'mySqlDataSource')

packages/repository/src/mixins/repository.mixin.ts

@@ -17,8 +17,8 @@ const debug = debugFactory('loopback:repository:mixin');
  * function to register a repository automatically. Also overrides
  * component function to allow it to register repositories automatically.
  *
+ * @example
  * ```ts
- *
  * class MyApplication extends RepositoryMixin(Application) {}
  * ```
  *
@@ -40,6 +40,7 @@ export function RepositoryMixin<T extends Class<any>>(superClass: T) {
      *
      * @param repoClass The repository to add.
      *
+     * @example
      * ```ts
      *
      * class NoteRepo {
@@ -93,6 +94,7 @@ export function RepositoryMixin<T extends Class<any>>(superClass: T) {
      * @param dataSource The dataSource to add.
      * @param name The binding name of the datasource; defaults to dataSource.name
      *
+     * @example
      * ```ts
      *
      * const ds: juggler.DataSource = new juggler.DataSource({
@@ -138,6 +140,7 @@ export function RepositoryMixin<T extends Class<any>>(superClass: T) {
      *
      * @param component The component to add.
      *
+     * @example
      * ```ts
      *
      * export class ProductComponent {
@@ -257,6 +260,7 @@ export class RepositoryMixinDoc {
    *
    * @param repo The repository to add.
    *
+   * @example
    * ```ts
    *
    * class NoteRepo {
@@ -300,6 +304,7 @@ export class RepositoryMixinDoc {
    * @param dataSource The dataSource to add.
    * @param name The binding name of the datasource; defaults to dataSource.name
    *
+   * @example
    * ```ts
    *
    * const ds: juggler.DataSource = new juggler.DataSource({
@@ -328,6 +333,7 @@ export class RepositoryMixinDoc {
    *
    * @param component The component to add.
    *
+   * @example
    * ```ts
    *
    * export class ProductComponent {