Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 4 commits into from
Jun 7, 2022
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
49eac4b
Improve readability of API Errors, Metadata and Types definitions by …
kriswest May 27, 2022
f270735
Correct wonky comment indentation
kriswest May 30, 2022
7eeef0d
Merge branch 'master' into format-api-docs-comments
kriswest May 30, 2022
dfe43c1
more comment cleanup
kriswest May 30, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 61 additions & 14 deletions docs/api/ref/Errors.md
View file
Open in desktop
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
Open in desktop
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 All @@ -85,16 +104,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;
}
```
Expand Down Expand Up @@ -157,18 +177,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 @@ -184,9 +210,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 @@ -202,35 +231,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 @@ -241,20 +269,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
Open in desktop
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 @@ -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`.

Expand Down