Skip to content

Commit

Permalink
Merge pull request #733 from finos/format-api-docs-comments
Browse files Browse the repository at this point in the history 
Improve readability of API Errors, Metadata and Types definitions in docs
  • Loading branch information
@kriswest
kriswest authored Jun 7, 2022
2 parents 302eb0f + dfe43c1 commit a6d09ef
Show file tree
Hide file tree
Showing 3 changed files with 148 additions and 68 deletions.
75 changes: 61 additions & 14 deletions docs/api/ref/Errors.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,44 +10,75 @@ 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)
Expand All @@ -57,16 +88,22 @@ 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)
Expand All @@ -75,18 +112,28 @@ 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)
Expand Down
130 changes: 79 additions & 51 deletions docs/api/ref/Metadata.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>;
}
Expand All @@ -30,37 +33,53 @@ 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>"). */
* 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>").
*/
readonly resultType?: string | null;
}
```
Expand Down Expand Up @@ -109,16 +128,17 @@ Metadata relating to a context or intent & context received through the `addCont
```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;
}
```
Expand Down Expand Up @@ -181,18 +201,24 @@ 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;

/** The calling application instance's own metadata, according to the Desktop Agent (MUST include at least the `appId` and `instanceId`). */
/** The calling application instance's own metadata, according to the
* Desktop Agent (MUST include at least the `appId` and `instanceId`).
*/
readonly appMetadata: AppMetadata;
}
```
Expand All @@ -208,9 +234,12 @@ 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;
}
```
Expand All @@ -226,35 +255,34 @@ The interface used to describe an intent within the platform.
```ts
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()`.

/** 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.

/** 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`
* established and returned by the app resolving the intent.

/** Retrieves a promise that will resolve to either `Context` data returned
* by the application that resolves the raised intent or a `Channel`
* established and returned by the app resolving the intent.
*
* A `Channel` returned MAY be of the `PrivateChannel` type. The
* client can then `addContextListener()` on that channel to, for example,
* receive a stream of data.
* A `Channel` returned MAY be of the `PrivateChannel` type. The
* client can then `addContextListener()` on that channel to, for example,
* receive a stream of data.
*
* If an error occurs (i.e. an error is thrown by the handler function,
* the promise it returns is rejected, or a promise is not returned by the
* handler function) then the Desktop Agent MUST reject the promise returned
* by the `getResult()` function of the `IntentResolution` with a string from
* the `ResultError` enumeration.
* If an error occurs (i.e. an error is thrown by the handler function,
* the promise it returns is rejected, or a promise is not returned by the
* handler function) then the Desktop Agent MUST reject the promise returned
* by the `getResult()` function of the `IntentResolution` with a string from
* the `ResultError` enumeration.
*/
getResult(): Promise<IntentResult>;
}
Expand All @@ -265,20 +293,20 @@ IntentResolution provides a standard format for data returned upon resolving an
#### Examples

```js
//resolve a "Chain" type intent
// Resolve a "Chain" type intent
let resolution = await agent.raiseIntent("intentName", context);

// Use metadata about the resolving app instance to target a further intent
try {
const resolution = await fdc3.raiseIntent('StageOrder', context);
...

//some time later
//Some time later
await agent.raiseIntent("UpdateOrder", context, resolution.source);
}
catch (err) { ... }

//resolve a "Client-Service" type intent with a data or channel response
//Resolve a "Client-Service" type intent with a data or channel response
let resolution = await agent.raiseIntent("intentName", context);
try {
const result = await resolution.getResult();
Expand Down
11 changes: 8 additions & 3 deletions docs/api/ref/Types.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
```
Expand Down Expand Up @@ -101,7 +106,7 @@ Optional metadata about the intent & context message, including the app that ori
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`.

Expand Down

0 comments on commit a6d09ef

Please sign in to comment.