search

alexa / alexa-apis-for-nodejs

The Alexa APIs for NodeJS consists of JS and Typescript definitions that represent the request and response JSON of Alexa services. These models act as core dependency for the Alexa Skills Kit NodeJS SDK (https://github.com/alexa/alexa-skills-kit-sdk-for-nodejs).
Apache License 2.0
60 stars 35 forks source link

Include API documentation on SMAPI SDK types. #17

Open sam-goodwin opened 3 years ago

sam-goodwin commented 3 years ago

SMAPI SDK types don't include much documentation. This introduces friction for developers by requiring they leave the context of the IDE to understand how to use the code. We should make sure to include comprehensive documentation on the types so that developers can jump around the types to learn and understand how it works.

For example, request payloads don't explain the request type or its fields:

/**
 *
 * @interface
 */
interface CreateSkillRequest {
  'vendorId'?: string;
  'manifest'?: v1.skill.Manifest.SkillManifest;
  'hosting'?: v1.skill.AlexaHosted.HostingConfiguration;
}

Functions only describe arguments, not the API:

/**
 *
 * @param {string} catalogId Provides a unique identifier of the catalog
 * @param {string} nextToken When response to this API call is truncated (that is, isTruncated response element value is true), the response also includes the nextToken element. The value of nextToken can be used in the next request as the continuation-token to list the next set of objects. The continuation token is an opaque value that Skill Management API understands. Token has expiry of 24 hours.
 * @param {number} maxResults Sets the maximum number of results returned in the response body. If you want to retrieve fewer than upper limit of 50 results, you can add this parameter to your request. maxResults should not exceed the upper limit. The response might contain fewer results than maxResults, but it will never contain more. If there are additional results that satisfy the search criteria, but these results were not returned, the response contains isTruncated = true.
 */
listUploadsForCatalogV0(catalogId: string, nextToken?: string, maxResults?: number): Promise<v0.catalog.upload.ListUploadsResponse>;

Can we re-use the public documentation or do we need more specific documentation for the code?

rahulawl commented 2 years ago

Is this issue/feature-request still relevant? We are working on prioritization of relevant issues and cleanup of rest. If we don’t hear back in 2 weeks, we will assume that the issue is not relevant and we will close it.