Standardize Example Format for Node Commands Documentation
Closed this issue · 2 comments
shohamazon commented
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.
shohamazon commented
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),
);
}
Yury-Fridlyand commented
I like that proposal.
Please, try to render it and publish it here as PDF