Documentation

Adding links

When adding links, surround the piece of text using square brackets and then put the link reference at the bottom of the comment block.

When creating links to other types, surround <Package>.<Type> with square brackets.

For example, this links valkey.io and the XPendingOptions type with the proper reference:

// Returns stream message summary information for pending messages matching a given range of IDs.
//
// See [valkey.io] for details.
//
// Parameters:
//
// key - The key of the stream.
// group - The consumer group name.
// opts - The options for the command. See [options.XPendingOptions] for details.
//
// Return value:
//
//  A slice of XPendingDetail structs, where each detail struct includes the following fields:
//
//  Id - The ID of the pending message.
//  ConsumerName - The name of the consumer that fetched the message and has still to acknowledge it.
//  IdleTime - The time in milliseconds since the last time the message was delivered to the consumer.
//  DeliveryCount - The number of times this message was delivered.
//
// [valkey.io]: https://valkey.io/commands/xpending/

Examples

In the Go client, we have runnable examples in the *_test.go files to supplement the documentation.

Use the following command to run all examples:

make example-test

Examples in Go are treated as tests by the framework. They must compile and execute without error and should return an OK response when run with the make example-test or go test commands.

Writing examples

To write an example for the command, find its respective group of commands and add the example to that *_test.go file. For example, ZAdd is a command that belongs to sorted_set_commands so we would add the example to sorted_set_commands_test.go.

According to which client you are working with, you can use getExampleClient() or getExampleClusterClient() for your examples.

Your example should look something like this:

// string_commands_test.go:


// Template
func ExampleClient_Get() {
    var client *Client = getExampleClient() // example helper function

    // General set up and code execution

    fmt.Println(result)

    // Output: [expected result]
}

There can only be a single Output: directive in an example and it should be the last item in the example func. For examples with a single print statement, you should put the expected result on the same line as the Output: directive. For examples with multiple print statements, include the expected output from each print statments on separate comment lines after the Output: directive. For example:

// Single-line example
func ExampleClient_Set() {
    var client *Client = getExampleClient() // example helper function

    result, err := client.Set("my_key", "my_value")
 if err != nil {
  fmt.Println("Glide example failed with an error: ", err)
 }
 fmt.Println(result)

 // Output: OK
}

// Multi-line example
func ExampleClient_Sort() {
 var client *Client = getExampleClient() // example helper function
 result, err := client.LPush("key1", []string{"1", "3", "2", "4"})
 result1, err := client.Sort("key1")
 if err != nil {
  fmt.Println("Glide example failed with an error: ", err)
 }
 fmt.Println(result)
 fmt.Println(result1)

 // Output:
 // 4
 // [{1 false} {2 false} {3 false} {4 false}]
}

For complex return types, it may be difficult to understand a response with multiple nested maps and arrays. Consider outputing the response as formatted JSON or use multiple print statements to break down and test key parts of the response. For example:

func ExampleClient_XPending() {
 var client *Client = getExampleClient() // example helper function

    // Setup here...

 summary, err := client.XPending(key, group)
 if err != nil {
  fmt.Println("Glide example failed with an error: ", err)
 }
 jsonSummary, _ := json.Marshal(summary)
 fmt.Println(string(jsonSummary))

 // Output: {"NumOfMessages":1,"StartId":{},"EndId":{},"ConsumerMessages":[{"ConsumerName":"c12345","MessageCount":1}]}
}

Function names for examples

pkgsite is a program which generates documentation for Go projects. To install and run it, execute the following:

# In the valkey-glide directory
cd go
go install golang.org/x/pkgsite/cmd/pkgsite@latest
pkgsite -open .

In order for pkgsite to work properly, examples for API must be written in a very specific format. They should be located in one of the *_test.go files in go directory and follow this pattern: Example<ClientType>_<FunctionName>(). If we wanted to create an example for the Get command in Client, we would name define our function as follows:

func ExampleClient_Get() {
    // Example code here
}

In cases where we want to show more than one example, we can add extra endings to the function names. Endings must begin with a lowercase letter:

// Bad: extension begins with upper case
func ExampleClient_Get_KeyExists() { ... }

// Bad: extension begins with number
func ExampleClient_Get_1() { ... }

// Good: extension begins with lower case letter
func ExampleClient_Get_one() { ... }

// Better: extension begins with lower case letter and is descriptive
func ExampleClient_Get_keyIsNil { ... }

Note: ClientType and FunctionName are CASE-SENSITIVE.