Improve readability of API Errors, Metadata and Types definitions in docs

docs/api/ref/Errors.md

@@ -10,44 +10,66 @@ Some FDC3 API operations return promises that can result in errors.
 enum OpenError {
   /** Returned if the specified application is not found.*/
   AppNotFound = 'AppNotFound',
+
   /** Returned if the specified application fails to launch correctly.*/
   ErrorOnLaunch = 'ErrorOnLaunch',
-  /** Returned if the specified application launches but fails to add a context listener in order to receive the context passed to the `fdc3.open` call.*/
+
+  /** Returned if the specified application launches but fails to add a context
+   * listener in order to receive the context passed to the `fdc3.open` call.*/
   AppTimeout = 'AppTimeout',
-  /** Returned if the FDC3 desktop agent implementation is not currently able to handle the request.*/
+
+  /** Returned if the FDC3 desktop agent implementation is not currently able
+   * to handle the request.*/
   ResolverUnavailable = 'ResolverUnavailable',
 }
 ```
 
 Contains constants representing the errors that can be encountered when calling the [`open`](DesktopAgent#open) method on the [DesktopAgent](DesktopAgent) object.
 
 #### See also
+
 * [`DesktopAgent.open`](DesktopAgent#open)
 
 ## `ResolveError`
 
 ```typescript
 export enum ResolveError {
-  /** SHOULD be returned if no apps are available that can resolve the intent and context combination.*/
+  /** SHOULD be returned if no apps are available that can resolve the intent
+   * and context combination.*/
   NoAppsFound = 'NoAppsFound',
-  /** Returned if the FDC3 desktop agent implementation is not currently able to handle the request.*/
+
+  /** Returned if the FDC3 desktop agent implementation is not currently able
+   * to handle the request.*/
   ResolverUnavailable = 'ResolverUnavailable',
-  /** Returned if the user cancelled the resolution request, for example by closing or cancelling a resolver UI.*/
+
+  /** Returned if the user cancelled the resolution request, for example by
+   * closing or cancelling a resolver UI.*/
   UserCancelled = 'UserCancelledResolution',
-  /** SHOULD be returned if a timeout cancels an intent resolution that required user interaction. Please use `ResolverUnavailable` instead for situations where a resolver UI or similar fails.*/
+
+  /** SHOULD be returned if a timeout cancels an intent resolution that
+   * required user interaction. Please use `ResolverUnavailable` instead for
+   * situations where a resolver UI or similar fails.*/
   ResolverTimeout = 'ResolverTimeout',
-  /** Returned if a specified target application is not available or a new instance of it cannot be opened. */
+
+  /** Returned if a specified target application is not available or a new
+   * instance of it cannot be opened. */
   TargetAppUnavailable = 'TargetAppUnavailable',
-  /** Returned if a specified target application instance is not available, for example because it has been closed. */
+
+  /** Returned if a specified target application instance is not available,
+   * for example because it has been closed. */
   TargetInstanceUnavailable = 'TargetInstanceUnavailable',
-  /** Returned if the intent and context could not be delivered to the selected application or instance, for example because it has not added an intent handler within a timeout.*/
+
+  /** Returned if the intent and context could not be delivered to the selected
+   * application or instance, for example because it has not added an intent
+   * handler within a timeout.*/
   IntentDeliveryFailed = 'IntentDeliveryFailed',
 }
 ```
 
 Contains constants representing the errors that can be encountered when calling the [`findIntent`](DesktopAgent#findintent), [`findIntentsByContext`](DesktopAgent#findintentsbycontext), [`raiseIntent`](DesktopAgent#raiseintent) or [`raiseIntentForContext`](DesktopAgent#raiseintentforcontext) methods on the [DesktopAgent](DesktopAgent).
 
 #### See also
+
 * [`DesktopAgent.findIntent`](DesktopAgent#findintent)
 * [`DesktopAgent.findIntentsByContext`](DesktopAgent#findintentsbycontext)
 * [`DesktopAgent.raiseIntent`](DesktopAgent#raiseintent)
@@ -57,16 +79,20 @@ Contains constants representing the errors that can be encountered when calling
 
 ```typescript
 enum ResultError {
-  /** Returned if the intent handler exited without returning a Promise or that Promise was not resolved with a Context or Channel object. */
+  /** Returned if the intent handler exited without returning a Promise or that
+   * Promise was not resolved with a Context or Channel object. */
   NoResultReturned = 'NoResultReturned',
-  /** Returned if the Intent handler function processing the raised intent throws an error or rejects the Promise it returned. */
+
+  /** Returned if the Intent handler function processing the raised intent
+   * throws an error or rejects the Promise it returned. */
   IntentHandlerRejected = 'IntentHandlerRejected',
 }
 ```
 
 Contains constants representing the errors that can be encountered when calling the [`getResult`](DesktopAgent#findintent) method on the [IntentResolution](Metadata#intentresolution) Object.
 
 #### See also
+
 * [`DesktopAgent.addIntentListener`](DesktopAgent#addintentlistener)
 * [`DesktopAgent.raiseIntent`](DesktopAgent#raiseintent)
 * [`IntentResolution`](Metadata#intentresolution)
@@ -75,18 +101,25 @@ Contains constants representing the errors that can be encountered when calling
 
 ```typescript
 enum ChannelError {
-  /** Returned if the specified channel is not found when attempting to join a channel via the `joinUserChannel` function of the DesktopAgent (`fdc3`).*/
+  /** Returned if the specified channel is not found when attempting to join a
+   * channel via the `joinUserChannel` function of the DesktopAgent (`fdc3`).*/
   NoChannelFound = 'NoChannelFound',
-  /** SHOULD be returned when a request to join a user channel or to a retrieve a Channel object via the `joinUserChannel` or `getOrCreateChannel` methods of the DesktopAgent (`fdc3`) object is denied. */
+
+  /** SHOULD be returned when a request to join a user channel or to a retrieve
+   * a Channel object via the `joinUserChannel` or `getOrCreateChannel` methods
+   * of the DesktopAgent (`fdc3`) object is denied. */
   AccessDenied = 'AccessDenied',
-  /** SHOULD be returned when a channel cannot be created or retrieved via the `getOrCreateChannel` method of the DesktopAgent (`fdc3`).*/
+
+  /** SHOULD be returned when a channel cannot be created or retrieved via the
+   * `getOrCreateChannel` method of the DesktopAgent (`fdc3`).*/
   CreationFailed = 'CreationFailed',
 }
 ```
 
 Contains constants representing the errors that can be encountered when calling channels using the [`joinUserChannel`](DesktopAgent#joinuserchannel) or [`getOrCreateChannel`](DesktopAgent#getorcreatechannel) methods, or the [`getCurrentContext`](Channel#getcurrentcontext), [`broadcast`](Channel#broadcast) or [`addContextListener`](Channel#addcontextlistener) methods on the `Channel` object.
 
 #### See also
+
 * [`DesktopAgent.joinUserChannel`](DesktopAgent#joinuserchannel)
 * [`DesktopAgent.getOrCreateChannel`](DesktopAgent#getorcreatechannel)
 * [`Channel.broadcast`](Channel#broadcast)

docs/api/ref/Metadata.md

@@ -8,8 +8,11 @@ FDC3 API operations return various types of metadata.
 
 ```ts
 interface AppIntent {
-  /** Details of the intent whose relationship to resolving applications is being described. */
+  /** Details of the intent whose relationship to resolving applications is
+   * being described.
+   */
   readonly intent: IntentMetadata;
+
   /** Details of applications that can resolve the intent. */
   readonly apps: Array<AppMetadata>;
 }
@@ -30,37 +33,52 @@ For each intent, it reference the applications that support that intent.
 ```ts
 interface AppMetadata extends AppIdentifier {
   /** 
-      The 'friendly' app name. 
-      This field was used with the `open` and `raiseIntent` calls in FDC3 <2.0, which now require an `AppIdentifier` wth `appId` set. 
-      Note that for display purposes the `title` field should be used, if set, in preference to this field.
+      The 'friendly' app name. This field was used with the `open` and
+      `raiseIntent` calls in FDC3 <2.0, which now require an `AppIdentifier`
+      with `appId` set. 
+
+      Note that for display purposes the `title` field should be used, if set,
+      in preference to this field.
    */
   readonly name?: string;
 
   /** The version of the application. */
   readonly version?: string;
 
-  /** An optional set of, implementation specific, metadata fields that can be used to disambiguate instances, such as a window title or screen position. Must only be set if `instanceId` is set. */
+  /** An optional set of, implementation specific, metadata fields that can be
+   *  used to disambiguate instances, such as a window title or screen position.
+   *  Must only be set if `instanceId` is set. 
+   */
   readonly instanceMetadata?: Record<string, any>;
 
-  /** A more user-friendly application title that can be used to render UI elements  */
+  /** A more user-friendly application title that can be used to render UI
+   * elements.
+   */
   readonly title?: string;
 
-  /**  A tooltip for the application that can be used to render UI elements */
+  /**  A tooltip for the application that can be used to render UI elements. */
   readonly tooltip?: string;
 
-  /** A longer, multi-paragraph description for the application that could include mark-up */
+  /** A longer, multi-paragraph description for the application that could
+   * include mark-up.
+   */
   readonly description?: string;
 
-  /** A list of icon URLs for the application that can be used to render UI elements */
+  /** A list of icon URLs for the application that can be used to render UI 
+   * elements.
+   */
   readonly icons?: Array<Icon>;
 
-  /** A list of image URLs for the application that can be used to render UI elements */
+  /** A list of image URLs for the application that can be used to render UI
+   * elements.
+   */
   readonly images?: Array<string>;
 
   /** The type of result returned for any intent specified during resolution. 
    * May express a particular context type (e.g. "fdc3.instrument"), channel 
    * (e.g. "channel") or a channel that will receive a specified type 
-   * (e.g. "channel<fdc3.instrument>"). */
+   * (e.g. "channel<fdc3.instrument>").
+   */
   readonly resultType?: string | null;
 }
 ```
@@ -85,16 +103,17 @@ Note that as `AppMetadata` instances are also `AppIdentifiers` they may be passe
 ```ts
 interface DisplayMetadata {
   /**
-   * A user-readable name for this channel, e.g: `"Red"`
-   */
+   * A user-readable name for this channel, e.g: `"Red"`. */
   readonly name?: string;
+
   /**
-   * The color that should be associated within this channel when displaying this channel in a UI, e.g: `#FF0000`. May be any color value supported by CSS, e.g. name, hex, rgba, etc..
-   */
+   * The color that should be associated within this channel when displaying
+   * this channel in a UI, e.g: `#FF0000`. May be any color value supported by
+   * CSS, e.g. name, hex, rgba, etc.. */
   readonly color?: string;
+
   /**
-   * A URL of an image that can be used to display this channel
-   */
+   * A URL of an image that can be used to display this channel. */
   readonly glyph?: string;
 }
 ```
@@ -157,13 +176,19 @@ The media type of the icon. If not provided the Desktop Agent may refer to the s
 
 ```ts
 interface ImplementationMetadata {
-  /** The version number of the FDC3 specification that the implementation provides.
-   *  The string must be a numeric semver version, e.g. 1.2 or 1.2.1.
+  /** The version number of the FDC3 specification that the implementation
+   *  provides. The string must be a numeric semver version, e.g. 1.2 or 1.2.1.
    */
   readonly fdc3Version: string;
-  /** The name of the provider of the FDC3 Desktop Agent Implementation (e.g. Finsemble, Glue42, OpenFin etc.). */
+
+  /** The name of the provider of the FDC3 Desktop Agent Implementation
+   * (e.g.Finsemble, Glue42, OpenFin etc.).
+   */
   readonly provider: string;
-  /** The version of the provider of the FDC3 Desktop Agent Implementation (e.g. 5.3.0). */
+
+  /** The version of the provider of the FDC3 Desktop Agent Implementation
+   * (e.g. 5.3.0).
+   */
   readonly providerVersion?: string;
 }
 ```
@@ -178,16 +203,19 @@ Metadata relating to the FDC3 [DesktopAgent](DesktopAgent) object and its provid
 
 ```ts
 interface IntentMetadata {
-  /** The unique name of the intent that can be invoked by the raiseIntent call */
+  /** The unique name of the intent that can be invoked by the raiseIntent call.
+   */
   readonly name: string;
-  /** A friendly display name for the intent that should be used to render UI elements */
+
+  /** A friendly display name for the intent that should be used to render UI
+   * elements.
+   */
   readonly displayName: string;
 }
 ```
 
 The interface used to describe an intent within the platform.
 
-
 #### See also
 
 * [`AppIntent.intent`](#appintent)
@@ -198,20 +226,23 @@ The interface used to describe an intent within the platform.
 interface IntentResolution {
 
   /** 
-   * Metadata about the app instance that was selected (or started) to resolve the intent.
-   * `source.instanceId` MUST be set, indicating the specific app instance that 
-   * received the intent.
+   * Metadata about the app instance that was selected (or started) to resolve
+   * the intent. `source.instanceId` MUST be set, indicating the specific app 
+   * instance that received the intent.
    */
   readonly source: AppMetadata;
+
   /**
    * The intent that was raised. May be used to determine which intent the user
    * chose in response to `fdc3.raiseIntentForContext()`.
    */
   readonly intent: string;
+
   /**
    * The version number of the Intents schema being used.
    */
   readonly version?: string;
+
   /**
    * Retrieves a promise that will resolve to either `Context` data returned 
    * by the application that resolves the raised intent or a `Channel` 

docs/api/ref/Types.md

@@ -12,9 +12,14 @@ If the `instanceId` field is set then the `AppMetadata` object represents a spec
 
 ```ts
 interface AppIdentifier {
-  /** The unique application identifier located within a specific application directory instance. An example of an appId might be 'app@sub.root' */
+  /** The unique application identifier located within a specific application
+   * directory instance. An example of an appId might be 'app@sub.root'.
+   */
   readonly appId: string;
-  /** An optional instance identifier, indicating that this object represents a specific instance of the application described.*/
+
+  /** An optional instance identifier, indicating that this object represents a
+   * specific instance of the application described.
+   */
   readonly instanceId?: string;
 }
 ```
@@ -95,7 +100,7 @@ Used when attaching listeners for raised intents.
 type IntentResult = Context | Channel;
 ```
 
-Describes results that an Intent handler may optionally return that should be communicated back to the app that raised the intent, via the [`IntentResolution`](Metadata#intentresolution). 
+Describes results that an Intent handler may optionally return that should be communicated back to the app that raised the intent, via the [`IntentResolution`](Metadata#intentresolution).
 
 Represented as a union type in TypeScript, however, this type may be rendered as an interface in other languages that both the `Context` and `Channel` types implement, allowing either to be returned by an `IntentHandler`.