aws/glide-for-redis

Standardize Example Format for Node Commands Documentation

Closed this issue · 2 comments

Currently, many commands in Node lack examples in their documentation, and those that do exist are inconsistent.

We've decided on a standard format for documenting examples in those commands:

/**
 * @example
 * ```typescript
 * // Example usage of the echo method
 * const echoedMessage = await client.echo("Glide-for-Redis");
 * console.log(echoedMessage); // Output: "Glide-for-Redis"
 * ```
 */

This format is applied to each example within the command documentation.

Please notice that this is a per example tag, so for every example you add, write the @example tag above, as we did in here:

/** Echoes the provided `message` back.
     * See https://redis.io/commands/echo for more details.
     *
     * @param message - The message to be echoed back.
     * @param route - The command will be routed to a random node, unless `route` is provided, in which
     *  case the client will route the command to the nodes defined by `route`.
     * @returns The provided `message`. When specifying a route other than a single node,
     *  it returns a dictionary where each address is the key and its corresponding node response is the value.
     *
     * @example
     * ```typescript
     * // Example usage of the echo command
     * const echoedMessage = await client.echo("Glide-for-Redis");
     * console.log(echoedMessage); // Output: "Glide-for-Redis"
     * ```
     * @example
     * ```typescript
     * // Example usage of the echo command with routing to all nodes
     * const echoedMessage = await client.echo("Glide-for-Redis", "allNodes");
     * console.log(echoedMessage); // Output: \{'addr': 'Glide-for-Redis', 'addr2': 'Glide-for-Redis', 'addr3': 'Glide-for-Redis'\}
     * ```
     */
    public echo(
        message: string,
        route?: Routes,
    ): Promise<ClusterResponse<string>> {
        return this.createWritePromise(
            createEcho(message),
            toProtobufRoute(route),
        );
    }

I like that proposal.
Please, try to render it and publish it here as PDF