Merge "Unification of manpages and docstrings"

2 files changed, 39 insertions, 24 deletions

diff --git a/doc/manpages/swift.1 b/doc/manpages/swift.1
index 4cfc23f..8672a11 100644
--- a/doc/manpages/swift.1
+++ b/doc/manpages/swift.1
@@ -36,25 +36,25 @@ several types of operations.
 .SH COMMANDS
 .PP
 
-\fBstat\fR [\fIcontainer\fR] [\fIobject\fR]
+\fBstat\fR [\fIcommand-options\fR] [\fIcontainer\fR] [\fIobject\fR]
 .RS 4
 Displays information for the account, container, or object depending on the args given (if any).
 In verbose mode, the Storage URL and the authentication token are displayed
-as well.
+as well. Option \-\-lh reports sizes in human readable format similar to ls \-lh.
 .RE
 
 \fBlist\fR [\fIcommand-options\fR] [\fIcontainer\fR]
 .RS 4
 Lists the containers for the account or the objects for a container.
-The \-p or \-\-prefix is an option that will only list items beginning
-with that prefix. The \-d or \-\-delimiter is option (for container listings only)
-that will roll up items with the given delimiter (see OpenStack Swift general
-documentation for what this means).
+The \-p <prefix> or \-\-prefix <prefix> is an option that will only list items beginning
+with that prefix. The \-d <delim> or \-\-delimiter <delim> is option
+(for container listings only) that will roll up items with the given
+delimiter (see OpenStack Swift general documentation for what this means).
 
-The \-l and \-\-lh options provide more detail, similar to ls \-l and ls \-lh, the latter
+The \-l or \-\-long and \-\-lh options provide more detail, similar to ls \-l and ls \-lh, the latter
 providing sizes in human readable format (eg 3K, 12M, etc). These latter 2 switches
 use more overhead to get those details, which is directly proportional to the number
-of container or objects being listed.
+of container or objects being listed. With the \-t or \-\-total option they only report totals.
 .RE
 
 \fBupload\fR [\fIcommand-options\fR] container file_or_directory [\fIfile_or_directory\fR] [...]
@@ -64,7 +64,7 @@ remaining args. The \-c or \-\-changed is an option that will only upload files
 that have changed since the last upload. The \-\-object-name <object\-name> is
 an option that will upload file and name object to <object-name> or upload dir
 and use <object\-name> as object prefix. The \-S <size> or \-\-segment\-size <size>
-and \-\-leave\-segments are options as well (see \-\-help for more).
+and \-\-leave\-segments and others are options as well (see swift upload \-\-help for more).
 .RE
 
 \fBpost\fR [\fIcommand-options\fR] [\fIcontainer\fR] [\fIobject\fR]
@@ -75,6 +75,7 @@ automatically; but this is not true for accounts and objects. Containers
 also allow the \-r (or \-\-read\-acl) and \-w (or \-\-write\-acl) options. The \-m
 or \-\-meta option is allowed on all and used to define the user meta data
 items to set in the form Name:Value. This option can be repeated.
+For more details and options see swift post \-\-help.
 \fBExample\fR: post \-m Color:Blue \-m Size:Large
 .RE
 
@@ -83,9 +84,10 @@ items to set in the form Name:Value. This option can be repeated.
 Downloads everything in the account (with \-\-all), or everything in a
 container, or a list of objects depending on the args given. For a single
 object download, you may use the \-o [\-\-output] <filename> option to
-redirect the output to a specific file or if "-" then just redirect to stdout.
+redirect the output to a specific file or if "-" then just redirect to stdout or
+with \-\-no-download actually not to write anything to disk.
 You can specify optional headers with the repeatable cURL-like option
-\-H [\-\-header].
+\-H [\-\-header]. For more details and options see swift download \-\-help.
 .RE
 
 \fBdelete\fR [\fIcommand-options\fR] [\fIcontainer\fR] [\fIobject\fR] [\fIobject\fR] [...]
@@ -93,6 +95,7 @@ You can specify optional headers with the repeatable cURL-like option
 Deletes everything in the account (with \-\-all), or everything in a container,
 or a list of objects depending on the args given. Segments of manifest objects
 will be deleted as well, unless you specify the \-\-leave\-segments option.
+For more details and options see swift delete \-\-help.
 .RE
 
 \fBcapabilities\fR [\fIproxy-url\fR]
@@ -104,7 +107,7 @@ is not provided the storage-url retrieved after authentication is used as
 proxy-url.
 .RE
 
-\fBtempurl\fR \fImethod\fR \fIseconds\fR \fIpath\fR \fIkey\fR [\fI--absolute\fR]
+\fBtempurl\fR [\fIcommand-option\fR] \fImethod\fR \fIseconds\fR \fIpath\fR \fIkey\fR
 .RS 4
 Generates a temporary URL allowing unauthenticated access to the Swift object
 at the given path, using the given HTTP method, for the given number of
@@ -114,20 +117,29 @@ should expire. \fBExample\fR: tempurl GET $(date -d "Jan 1 2016" +%s)
 /v1/AUTH_foo/bar_container/quux.md my_secret_tempurl_key --absolute
 .RE
 
+\fBauth\fR
+.RS 4
+Display auth related authentication variables in shell friendly format.
+For examples see swift auth \-\-help.
+.RE
+
 .SH OPTIONS
 .PD 0
 .IP "--version              Show program's version number and exit"
-.IP "-h, --help             Show this (or any subcommand) help message and exit"
+.IP "-h, --help             Show this (or any subcommand if after command) help message and exit"
 .IP "-s, --snet             Use SERVICENET internal network"
 .IP "-v, --verbose          Print more info"
 .IP "-q, --quiet            Suppress status output"
 .IP "-A AUTH, --auth=AUTH   URL for obtaining an auth token "
 .IP "-U USER, --user=USER   User name for obtaining an auth token"
-.IP "-V 1|2                 Authentication protocol version"
+.IP "-V 1|2, --auth-version=VERSION  Authentication protocol version"
 .IP "-K KEY, --key=KEY      Key for obtaining an auth token"
 .IP "--os-storage-url=URL   Use this instead of URL returned from auth"
-
+.IP "--os-help              Show all OpenStack authentication options"
 .PD
+.RS 4
+For more options see swift \-\-help and swift \-\-os-help.
+.RE
 
 
 .SH EXAMPLE
diff --git a/swiftclient/shell.py b/swiftclient/shell.py
index f7c2476..8fc5c0c 100755
--- a/swiftclient/shell.py
+++ b/swiftclient/shell.py
@@ -54,15 +54,15 @@ def immediate_exit(signum, frame):
 st_delete_options = '''[--all] [--leave-segments]
                     [--object-threads <threads>]
                     [--container-threads <threads>]
-                    <container> [object]
+                    [<container>] [<object>] [...]
 '''
 
 st_delete_help = '''
 Delete a container or objects within a container.
 
 Positional arguments:
-  <container>           Name of container to delete from.
-  [object]              Name of object to delete. Specify multiple times
+  [<container>]         Name of container to delete from.
+  [<object>]            Name of object to delete. Specify multiple times
                         for multiple objects.
 
 Optional arguments:
@@ -156,7 +156,7 @@ st_download_options = '''[--all] [--marker] [--prefix <prefix>]
                       [--object-threads <threads>]
                       [--container-threads <threads>] [--no-download]
                       [--skip-identical] [--remove-prefix]
-                      [--header <header:value>]
+                      [--header <header:value>] [--no-shuffle]
                       <container> <object>
 '''
 
@@ -376,7 +376,7 @@ def st_download(parser, args, output_manager):
 
 
 st_list_options = '''[--long] [--lh] [--totals] [--prefix <prefix>]
-                  [--delimiter <delimiter>]
+                  [--delimiter <delimiter>] [container]
 '''
 
 st_list_help = '''
@@ -390,8 +390,10 @@ Optional arguments:
   --lh                  Report sizes in human readable format similar to
                         ls -lh.
   -t, --totals          Used with -l or --lh, only report totals.
-  -p, --prefix          Only list items beginning with the prefix.
-  -d, --delimiter       Roll up items with the given delimiter. For containers
+  -p <prefix>, --prefix <prefix>
+                        Only list items beginning with the prefix.
+  -d <delim>, --delimiter <delim>
+                        Roll up items with the given delimiter. For containers
                         only. See OpenStack Swift API documentation for what
                         this means.
 '''.strip('\n')
@@ -690,7 +692,7 @@ st_upload_options = '''[--changed] [--skip-identical] [--segment-size <size>]
                     [--object-threads <thread>] [--segment-threads <threads>]
                     [--header <header>] [--use-slo] [--ignore-checksum]
                     [--object-name <object-name>]
-                    <container> <file_or_directory>
+                    <container> <file_or_directory> [<file_or_directory>] [...]
 '''
 
 st_upload_help = ''' Uploads specified files and directories to the given container.
@@ -1006,7 +1008,8 @@ def st_auth(parser, args, thread_manager):
         print('export OS_AUTH_TOKEN=%s' % sh_quote(token))
 
 
-st_tempurl_options = '<method> <seconds> <path> <key>'
+st_tempurl_options = '''[--absolute]
+                     <method> <seconds> <path> <key>'''
 
 
 st_tempurl_help = '''