Update documentation to explain redisConnectWithOptions.

Additionally document the new `REDIS_OPT_PREFER_IPV4`,
`REDIS_OPT_PREFER_IPV6` as well as the rest of our existing options.

See #1096

1 files changed, 35 insertions, 0 deletions

diff --git a/README.md b/README.md
index ff50d13..661325c 100644
--- a/README.md
+++ b/README.md
@@ -82,6 +82,7 @@ an error state. The field `errstr` will contain a string with a description of
 the error. More information on errors can be found in the **Errors** section.
 After trying to connect to Redis using `redisConnect` you should
 check the `err` field to see if establishing the connection was successful:
+
 ```c
 redisContext *c = redisConnect("127.0.0.1", 6379);
 if (c == NULL || c->err) {
@@ -94,6 +95,40 @@ if (c == NULL || c->err) {
 }
 ```
 
+One can also use `redisConnectWithOptions` which takes a `redisOptions` argument
+that can be configured with endpoint information as well as many different flags
+to change how the `redisContext` will be configured.
+
+```c
+redisOptions opt = {0};
+
+/* One can set the endpoint with one of our helper macros */
+if (tcp) {
+    REDIS_OPTIONS_SET_TCP(&opt, "localhost", 6379);
+} else {
+    REDIS_OPTIONS_SET_UNIX(&opt, "/tmp/redis.sock");
+}
+
+/* And privdata can be specified with another helper */
+REDIS_OPTIONS_SET_PRIVDATA(&opt, myPrivData, myPrivDataDtor);
+
+/* Finally various options may be set via the `options` member, as described below */
+opt->options |= REDIS_OPT_PREFER_IPV4;
+```
+
+### Configurable redisOptions flags
+
+There are several flags you may set in the `redisOptions` struct to change default behavior.  You can specify the flags via the `redisOptions->options` member.
+
+| Flag | Description  |
+| --- | --- |
+| REDIS\_OPT\_NONBLOCK | Tells hiredis to make a non-blocking connection. |
+| REDIS\_OPT\_REUSEADDR | Tells hiredis to set the [SO_REUSEADDR](https://man7.org/linux/man-pages/man7/socket.7.html) socket option |
+| REDIS\_OPT\_PREFER\_IPV4<br>REDIS\_OPT\_PREFER_IPV6 | Informs hiredis to either prefer `IPV4` or `IPV6` when invoking [getaddrinfo](https://man7.org/linux/man-pages/man3/gai_strerror.3.html).  Note that both of the options may be set at once, which will cause hiredis to spcify `AF_UNSPEC` in the getaddrinfo call, which means both `IPV4` and `IPV6` addresses will be searched simultaneously. | 
+| REDIS\_OPT\_NO\_PUSH\_AUTOFREE | Tells hiredis to not install the default RESP3 PUSH handler (which just intercepts and frees the replies).  This is useful in situations where you want to process these messages in-band. |
+| REDIS\_OPT\_NOAUOTFREEREPLIES | **ASYNC**: tells hiredis not to automatically invoke `freeReplyObject` after executing the reply callback. |
+| REDIS\_OPT\_NOAUTOFREE | **ASYNC**: Tells hiredis not to automatically free the `redisAsyncContext` on connection/communication failure, but only if the user makes an explicit call to `redisAsyncDisconnect` or `redisAsyncFree` |
+
 *Note: A `redisContext` is not thread-safe.*
 
 ### Sending commands