From 9a81d46611dd5b673cee7710e4284d2fd36a4618 Mon Sep 17 00:00:00 2001 From: Michael Wallner Date: Thu, 23 Feb 2023 10:49:43 +0100 Subject: [PATCH] fix #134: docs: update client options --- ChangeLog-1.1.md | 4 ++- docs/source/ChangeLog-1.1.rst | 4 ++- docs/source/bin/memaslap.rst | 11 +++++++- docs/source/bin/memcapable.rst | 6 +++++ docs/source/bin/memcat.rst | 9 +++---- docs/source/bin/memcp.rst | 33 ++++++++++++++---------- docs/source/bin/memdump.rst | 8 +++--- docs/source/bin/memerror.rst | 1 + docs/source/bin/memexist.rst | 4 +-- docs/source/bin/memflush.rst | 4 +-- docs/source/bin/memping.rst | 5 ++++ docs/source/bin/memrm.rst | 5 +--- docs/source/bin/memslap.rst | 30 +++++++++++++++++++-- docs/source/bin/memstat.rst | 31 +++++++++++++++------- docs/source/bin/memtouch.rst | 6 ++--- docs/source/bin/options/all.rst | 4 +-- docs/source/bin/options/common.rst | 17 +++--------- docs/source/bin/options/common_get.rst | 6 +++++ docs/source/bin/options/common_set.rst | 8 ++++++ docs/source/bin/options/expire.rst | 2 +- docs/source/bin/options/file_out.rst | 6 +++++ docs/source/bin/options/flag.rst | 4 --- docs/source/bin/options/flags_noarg.rst | 4 +++ docs/source/bin/options/flags_reqarg.rst | 4 +++ docs/source/bin/options/hash.rst | 2 +- docs/source/bin/options/net.rst | 12 +++++++++ docs/source/bin/options/proto.rst | 8 ++++++ docs/source/bin/options/sasl.rst | 4 +-- docs/source/bin/options/udp.rst | 2 +- 29 files changed, 166 insertions(+), 78 deletions(-) create mode 100644 docs/source/bin/options/common_get.rst create mode 100644 docs/source/bin/options/common_set.rst create mode 100644 docs/source/bin/options/file_out.rst delete mode 100644 docs/source/bin/options/flag.rst create mode 100644 docs/source/bin/options/flags_noarg.rst create mode 100644 docs/source/bin/options/flags_reqarg.rst create mode 100644 docs/source/bin/options/net.rst create mode 100644 docs/source/bin/options/proto.rst diff --git a/ChangeLog-1.1.md b/ChangeLog-1.1.md index b6ecaa77..851c730b 100644 --- a/ChangeLog-1.1.md +++ b/ChangeLog-1.1.md @@ -4,10 +4,12 @@ > released TBA -* Fix [gh #132](https://github.com/awesomized/libmemcached/issues/132): +* Fix [gh #107](https://github.com/awesomized/libmemcached/issues/107): macOS: deprecated sasl API (improve detection of `libsasl2`). * Fix [gh #132](https://github.com/awesomized/libmemcached/issues/132): Add build of static library (with `cmake -DBUILD_SHARED_LIBS=OFF`). +* Fix [gh #134](https://github.com/awesomized/libmemcached/issues/134): + Update client option documentation. * Fix [gh #136](https://github.com/awesomized/libmemcached/issues/136): `libmemcachedutil` is underlinked (link against libmemcached). diff --git a/docs/source/ChangeLog-1.1.rst b/docs/source/ChangeLog-1.1.rst index e79cad3e..1582019a 100644 --- a/docs/source/ChangeLog-1.1.rst +++ b/docs/source/ChangeLog-1.1.rst @@ -14,10 +14,12 @@ v1.1.4 -* Fix `gh #132 `_\ : +* Fix `gh #107 `_\ : macOS: deprecated sasl API (improve detection of ``libsasl2``\ ). * Fix `gh #132 `_\ : Add build of static library (with ``cmake -DBUILD_SHARED_LIBS=OFF``\ ). +* Fix `gh #134 `_\ : + Update client option documentation. * Fix `gh #136 `_\ : ``libmemcachedutil`` is underlinked (link against libmemcached). diff --git a/docs/source/bin/memaslap.rst b/docs/source/bin/memaslap.rst index 240c9281..ab311d73 100644 --- a/docs/source/bin/memaslap.rst +++ b/docs/source/bin/memaslap.rst @@ -10,6 +10,7 @@ memaslap [options] .. program:: memaslap .. option:: --help +.. option:: --servers .. envvar:: MEMCACHED_SERVERS @@ -29,7 +30,7 @@ the threads don't communicate with each other, and there are several socket connections in each thread. Each connection keeps key size distribution, value size distribution, and command distribution by itself. -You can specify servers via the :option:`memslap --servers` option or via the +You can specify servers via the :option:`memaslap --servers` option or via the environment variable :envvar:`MEMCACHED_SERVERS`. FEATURES @@ -999,6 +1000,14 @@ memaslap -s 127.0.0.1:11211,127.0.0.1:11212 -F config -t 2m memaslap -s 127.0.0.1:11211,127.0.0.1:11212 -F config -t 2m -p 2 +NOTE +---- + +This is a contributed program. + +This program doesn't follow the standard flag/option scheme. + + SEE ALSO -------- diff --git a/docs/source/bin/memcapable.rst b/docs/source/bin/memcapable.rst index d1a4f7a4..374c9c33 100644 --- a/docs/source/bin/memcapable.rst +++ b/docs/source/bin/memcapable.rst @@ -39,6 +39,12 @@ OPTIONS Set the timeout for an IO operation to/from the server to \ *n*\ seconds. +NOTE +---- + +This program doesn't follow the standard flag/option scheme. + + SEE ALSO -------- diff --git a/docs/source/bin/memcat.rst b/docs/source/bin/memcat.rst index aa6cc540..36f6a6bb 100644 --- a/docs/source/bin/memcat.rst +++ b/docs/source/bin/memcat.rst @@ -23,13 +23,10 @@ It is similar to the standard UNIX :manpage:`cat(1)` utility. OPTIONS ------- -.. include:: options/all.rst -.. include:: options/common.rst +.. include:: options/common_get.rst +.. include:: options/flags_noarg.rst .. include:: options/hash.rst - -.. option:: --flag - - Display stored flags. +.. include:: options/file_out.rst ENVIRONMENT ----------- diff --git a/docs/source/bin/memcp.rst b/docs/source/bin/memcp.rst index deea12a7..7d82a590 100644 --- a/docs/source/bin/memcp.rst +++ b/docs/source/bin/memcp.rst @@ -21,31 +21,36 @@ The key names will be the names of the files, without any directory path. OPTIONS ------- -.. include:: options/all.rst -.. include:: options/common.rst -.. include:: options/expire.rst -.. include:: options/flag.rst -.. include:: options/hash.rst -.. include:: options/sasl.rst +.. include:: options/common_set.rst +.. include:: /bin/options/flags_reqarg.rst .. include:: options/udp.rst -.. option:: --buffer - - Enable internal buffering of commands. - -.. option:: --set +.. option:: -S|--set Issue *SET* command(s). This is the default mode. - See also :option:`--add` and :option:`--replace`. + See also :option:`-A|--add` and :option:`-R|--replace`. -.. option:: --add +.. option:: -A|--add Issue *ADD* command(s). -.. option:: --replace +.. option:: -R|--replace Issue *REPLACE* command(s). +.. option:: -.|--basename + + Use basename of path as key (default). + +.. option:: -+|--relative + + Use relative path (as passed), instead of basename only. + +.. option:: -/|--absolute + + Use absolute path (real path), instead of basename only. + + ENVIRONMENT ----------- diff --git a/docs/source/bin/memdump.rst b/docs/source/bin/memdump.rst index 07eb2fff..a24e4085 100644 --- a/docs/source/bin/memdump.rst +++ b/docs/source/bin/memdump.rst @@ -20,11 +20,9 @@ provide all keys it is not possible to get a complete "dump". OPTIONS ------- -.. include:: options/all.rst -.. include:: options/common.rst -.. include:: options/hash.rst -.. include:: options/sasl.rst - +.. include:: options/common_get.rst +.. include:: options/file_out.rst + ENVIRONMENT ----------- diff --git a/docs/source/bin/memerror.rst b/docs/source/bin/memerror.rst index 525aaf63..caa6b497 100644 --- a/docs/source/bin/memerror.rst +++ b/docs/source/bin/memerror.rst @@ -20,6 +20,7 @@ OPTIONS ------- .. include:: options/all.rst +.. include:: options/common.rst ENVIRONMENT ----------- diff --git a/docs/source/bin/memexist.rst b/docs/source/bin/memexist.rst index 1859c838..52832b16 100644 --- a/docs/source/bin/memexist.rst +++ b/docs/source/bin/memexist.rst @@ -18,10 +18,8 @@ DESCRIPTION OPTIONS ------- -.. include:: options/all.rst -.. include:: options/common.rst +.. include:: options/common_get.rst .. include:: options/hash.rst -.. include:: options/sasl.rst ENVIRONMENT ----------- diff --git a/docs/source/bin/memflush.rst b/docs/source/bin/memflush.rst index ed84d9a9..b752b6eb 100644 --- a/docs/source/bin/memflush.rst +++ b/docs/source/bin/memflush.rst @@ -22,9 +22,7 @@ DESCRIPTION OPTIONS ------- -.. include:: options/all.rst -.. include:: options/common.rst -.. include:: options/sasl.rst +.. include:: options/common_get.rst .. include:: options/expire.rst .. note:: diff --git a/docs/source/bin/memping.rst b/docs/source/bin/memping.rst index fff7db22..aaae7a7a 100644 --- a/docs/source/bin/memping.rst +++ b/docs/source/bin/memping.rst @@ -22,6 +22,11 @@ OPTIONS .. include:: options/common.rst .. include:: options/sasl.rst +.. option:: -s|--servers + + Specify the list of servers as *hostname[:port][,hostname[:port]...]*. + + ENVIRONMENT ----------- diff --git a/docs/source/bin/memrm.rst b/docs/source/bin/memrm.rst index e3edd319..94da5a7b 100644 --- a/docs/source/bin/memrm.rst +++ b/docs/source/bin/memrm.rst @@ -18,10 +18,7 @@ DESCRIPTION OPTIONS ------- -.. include:: options/all.rst -.. include:: options/common.rst -.. include:: options/hash.rst -.. include:: options/sasl.rst +.. include:: options/common_set.rst ENVIRONMENT ----------- diff --git a/docs/source/bin/memslap.rst b/docs/source/bin/memslap.rst index 1abf45f6..bd99ab49 100644 --- a/docs/source/bin/memslap.rst +++ b/docs/source/bin/memslap.rst @@ -21,8 +21,34 @@ throughput, and so on. OPTIONS ------- -.. include:: options/all.rst -.. include:: options/common.rst +.. include:: options/common_get.rst +.. include:: options/hash.rst +.. include:: options/udp.rst + +.. option:: -R|--noreply + + Enable the NOREPLY behavior for storage commands. + +.. option:: -F|--flush + + Flush all servers prior test. + +.. option:: -t|--test + + Test to perform (options: get, mget, set; default: get). + +.. option:: -c|--concurrency + + Concurrency (number of threads to start; default: 1). + +.. option:: -e|--execute-number + + Number of times to execute the tests (default: 10000). + +.. option:: -l|--initial-load + + Number of keys to load before executing tests (default: 10000). + ENVIRONMENT ----------- diff --git a/docs/source/bin/memstat.rst b/docs/source/bin/memstat.rst index 3b440de9..7c2b9625 100644 --- a/docs/source/bin/memstat.rst +++ b/docs/source/bin/memstat.rst @@ -4,7 +4,7 @@ memstat SYNOPSIS -------- -memstat [options] +memstat [options] [stat args] .. program:: memstat @@ -19,25 +19,36 @@ It prints all data to stdout. OPTIONS ------- -.. include:: options/all.rst -.. include:: options/common.rst -.. include:: options/sasl.rst +.. include:: options/common_get.rst -.. option:: --analyze +.. option:: -A|--args - Analyze and print differences of a server cluster. A memory and uptime comparison is performed by default. + Stat args. - Available additional modes: + **DEPRECATED:** use positional arguments. - --analyze=latency - Network latency comparison +.. option:: -a|--analyze [] + + Analyze and print differences of a server cluster. + A memory and uptime comparison is performed by default. + Options: + + --analyze[=default] + Memory and uptime comparison. + --analyze=latency + Network latency comparison. -.. option:: --server-version +.. option:: -S|-server-version Obtain and print server version(s) only. +.. option:: --iterations + + Iteration count of GETs sent by the latency test (default: 1000). + + ENVIRONMENT ----------- diff --git a/docs/source/bin/memtouch.rst b/docs/source/bin/memtouch.rst index 4e55ab15..c9e03406 100644 --- a/docs/source/bin/memtouch.rst +++ b/docs/source/bin/memtouch.rst @@ -16,11 +16,9 @@ DESCRIPTION OPTIONS ------- -.. include:: options/all.rst -.. include:: options/common.rst -.. include:: options/expire.rst +.. include:: options/common_get.rst .. include:: options/hash.rst -.. include:: options/sasl.rst +.. include:: options/expire.rst SEE ALSO -------- diff --git a/docs/source/bin/options/all.rst b/docs/source/bin/options/all.rst index 5955282d..951b2ee1 100644 --- a/docs/source/bin/options/all.rst +++ b/docs/source/bin/options/all.rst @@ -1,8 +1,8 @@ -.. option:: --help +.. option:: -h|--help Display help. -.. option:: --version +.. option:: -V|--version Display version. diff --git a/docs/source/bin/options/common.rst b/docs/source/bin/options/common.rst index 9acb684d..04802b75 100644 --- a/docs/source/bin/options/common.rst +++ b/docs/source/bin/options/common.rst @@ -1,20 +1,11 @@ -.. option:: --quiet +.. option:: -q|--quiet Operate quietly. -.. option:: --verbose +.. option:: -v|--verbose Operate more verbosely. -.. option:: --debug - - See :option:`--verbose`. - -.. option:: --servers - - Specify the list of servers as *hostname[:port][,hostname[:port]...]*. - -.. option:: --binary - - Enable binary protocol. +.. option:: -d|--debug + See :option:`-v\|--verbose`. diff --git a/docs/source/bin/options/common_get.rst b/docs/source/bin/options/common_get.rst new file mode 100644 index 00000000..74169301 --- /dev/null +++ b/docs/source/bin/options/common_get.rst @@ -0,0 +1,6 @@ + +.. include:: /bin/options/all.rst +.. include:: /bin/options/common.rst +.. include:: /bin/options/net.rst +.. include:: /bin/options/proto.rst +.. include:: /bin/options/sasl.rst diff --git a/docs/source/bin/options/common_set.rst b/docs/source/bin/options/common_set.rst new file mode 100644 index 00000000..e4cf8f06 --- /dev/null +++ b/docs/source/bin/options/common_set.rst @@ -0,0 +1,8 @@ + +.. include:: /bin/options/all.rst +.. include:: /bin/options/common.rst +.. include:: /bin/options/expire.rst +.. include:: /bin/options/hash.rst +.. include:: /bin/options/net.rst +.. include:: /bin/options/proto.rst +.. include:: /bin/options/sasl.rst diff --git a/docs/source/bin/options/expire.rst b/docs/source/bin/options/expire.rst index 2f609356..9fcd170d 100644 --- a/docs/source/bin/options/expire.rst +++ b/docs/source/bin/options/expire.rst @@ -1,4 +1,4 @@ -.. option:: --expire +.. option:: -e|--expire Use *expiration* seconds (or a UNIX timestamp). diff --git a/docs/source/bin/options/file_out.rst b/docs/source/bin/options/file_out.rst new file mode 100644 index 00000000..21de3162 --- /dev/null +++ b/docs/source/bin/options/file_out.rst @@ -0,0 +1,6 @@ + +.. option:: -f|--file [] + + Output to file instead of standard output. + + *NOTE:* defaults to if no argument was provided. diff --git a/docs/source/bin/options/flag.rst b/docs/source/bin/options/flag.rst deleted file mode 100644 index f6d2618f..00000000 --- a/docs/source/bin/options/flag.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. option:: --flag - - Use *number* as flag. - diff --git a/docs/source/bin/options/flags_noarg.rst b/docs/source/bin/options/flags_noarg.rst new file mode 100644 index 00000000..f0801638 --- /dev/null +++ b/docs/source/bin/options/flags_noarg.rst @@ -0,0 +1,4 @@ +.. option:: -F|--flags + + Display key's flags. + diff --git a/docs/source/bin/options/flags_reqarg.rst b/docs/source/bin/options/flags_reqarg.rst new file mode 100644 index 00000000..999329cb --- /dev/null +++ b/docs/source/bin/options/flags_reqarg.rst @@ -0,0 +1,4 @@ +.. option:: -F|--flags + + Use *number* as key's flags. + diff --git a/docs/source/bin/options/hash.rst b/docs/source/bin/options/hash.rst index 78d84dee..00c3df5c 100644 --- a/docs/source/bin/options/hash.rst +++ b/docs/source/bin/options/hash.rst @@ -1,4 +1,4 @@ -.. option:: --hash +.. option:: -H|--hash Use *algorithm* as key hash algo. See :enumerator:`memcached_behavior_t::MEMCACHED_BEHAVIOR_HASH`. diff --git a/docs/source/bin/options/net.rst b/docs/source/bin/options/net.rst new file mode 100644 index 00000000..3c2bf709 --- /dev/null +++ b/docs/source/bin/options/net.rst @@ -0,0 +1,12 @@ + +.. option:: -s|--servers + + Specify the list of servers as *hostname[:port][,hostname[:port]...]*. + +.. option:: -n|--non-blocking + + Enable non-blocking operations. + +.. option:: -N|--tcp-nodelay + + Disable Nagle's algorithm. diff --git a/docs/source/bin/options/proto.rst b/docs/source/bin/options/proto.rst new file mode 100644 index 00000000..97d015b9 --- /dev/null +++ b/docs/source/bin/options/proto.rst @@ -0,0 +1,8 @@ + +.. option:: -b|--binary + + Enable binary protocol. + +.. option:: -B|--buffer + + Buffer requests. diff --git a/docs/source/bin/options/sasl.rst b/docs/source/bin/options/sasl.rst index 8d664c34..33feee7a 100644 --- a/docs/source/bin/options/sasl.rst +++ b/docs/source/bin/options/sasl.rst @@ -1,8 +1,8 @@ -.. option:: --username +.. option:: -u|--username Use *username* for SASL authentication. -.. option:: --password +.. option:: -p|--password Use *password* for SASL authentication. diff --git a/docs/source/bin/options/udp.rst b/docs/source/bin/options/udp.rst index ae486b3e..4c5e8d13 100644 --- a/docs/source/bin/options/udp.rst +++ b/docs/source/bin/options/udp.rst @@ -1,4 +1,4 @@ -.. option:: --udp +.. option:: -U|--udp Enable UDP operation mode. -- 2.30.2