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.

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

docs: add thrown exceptions to command documentation #715

Merged
merged 4 commits into from
Mar 10, 2023

Conversation

kuhe
Copy link
Contributor

@kuhe kuhe commented Mar 10, 2023

This adds the modeled errors of each operation to the JSDoc block of the corresponding command.

This will generate useful links in API documentation. The @throws entries appear directly after the existing links to the command input, output, and client config.

The current documentation makes it impossible to find which exceptions are modeled with an operation without consulting the Smithy model declaration file. This will help API documentation readers or source code readers write their error handling switch cases.

Example:

/**
 * <p>Returns the content of the specified pronunciation lexicon stored
 *       in an Amazon Web Services Region. For more information, see <a href="https://docs.aws.amazon.com/polly/latest/dg/managing-lexicons.html">Managing Lexicons</a>.</p>
 * @example
 * Use a bare-bones client and the command you need to make an API call.
 * ```javascript
 * import { PollyClient, GetLexiconCommand } from "@aws-sdk/client-polly"; // ES Modules import
 * // const { PollyClient, GetLexiconCommand } = require("@aws-sdk/client-polly"); // CommonJS import
 * const client = new PollyClient(config);
 * const command = new GetLexiconCommand(input);
 * const response = await client.send(command);
 * ```
 *
 * @see {@link GetLexiconCommandInput} for command's `input` shape.
 * @see {@link GetLexiconCommandOutput} for command's `response` shape.
 * @see {@link PollyClientResolvedConfig | config} for PollyClient's `config` shape.
 *
 * @throws {@link LexiconNotFoundException} (client) <p>Amazon Polly can't find the specified lexicon. This could be caused by a
 *       lexicon that is missing, its name is misspelled or specifying a lexicon
 *       that is in a different region.</p>
 *          <p>Verify that the lexicon exists, is in the region (see <a>ListLexicons</a>) and that you spelled its name is spelled
 *       correctly. Then try again.</p>
 * @throws {@link ServiceFailureException} (server) <p>An unknown condition has caused a service failure.</p>
 *
  • a JSv3 codegen change (TBD) will be committed alongside this if approved.

@kuhe kuhe merged commit ec6aaf8 into smithy-lang:main Mar 10, 2023
@kuhe kuhe deleted the docs/throws branch March 10, 2023 21:31
srchase pushed a commit to srchase/smithy-typescript that referenced this pull request Mar 17, 2023
* docs: add thrown exceptions to command documentation

* remove trailing spaces

* string formatting

* tsdoc format
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants