From b599b48f69d6c6b192bd0ae7ae4a493434761958 Mon Sep 17 00:00:00 2001
From: Alistair Coles <alistairncoles@gmail.com>
Date: Wed, 26 Jul 2017 12:53:46 +0100
Subject: [PATCH] Clarify usage of replicator and reconstructor override
 options

Clarify in usage statement and man pages that CLI override options for
swift-object-reconstructor and swift-object-replicator only have
effect when --once is used.

Also add a link to object reconstructor source code docs to the doc
index page for consistency with the other object services.

Change-Id: If348b340d59a672d3a19d4df231ebdb74f4aed51
---
 bin/swift-object-reconstructor            |  6 ++--
 bin/swift-object-replicator               |  9 ++++--
 doc/manpages/swift-object-reconstructor.1 | 11 ++++---
 doc/manpages/swift-object-replicator.1    | 39 +++++++++++++----------
 doc/source/object.rst                     | 10 ++++++
 5 files changed, 49 insertions(+), 26 deletions(-)

diff --git a/bin/swift-object-reconstructor b/bin/swift-object-reconstructor
index ee4c5d6436..2c28437cd8 100755
--- a/bin/swift-object-reconstructor
+++ b/bin/swift-object-reconstructor
@@ -23,9 +23,11 @@ if __name__ == '__main__':
     parser = OptionParser("%prog CONFIG [options]")
     parser.add_option('-d', '--devices',
                       help='Reconstruct only given devices. '
-                           'Comma-separated list')
+                           'Comma-separated list. '
+                           'Only has effect if --once is used.')
     parser.add_option('-p', '--partitions',
                       help='Reconstruct only given partitions. '
-                           'Comma-separated list')
+                           'Comma-separated list. '
+                           'Only has effect if --once is used.')
     conf_file, options = parse_options(parser=parser, once=True)
     run_daemon(ObjectReconstructor, conf_file, **options)
diff --git a/bin/swift-object-replicator b/bin/swift-object-replicator
index ed3cb8521d..7a53470a8b 100755
--- a/bin/swift-object-replicator
+++ b/bin/swift-object-replicator
@@ -23,12 +23,15 @@ if __name__ == '__main__':
     parser = OptionParser("%prog CONFIG [options]")
     parser.add_option('-d', '--devices',
                       help='Replicate only given devices. '
-                           'Comma-separated list')
+                           'Comma-separated list. '
+                           'Only has effect if --once is used.')
     parser.add_option('-p', '--partitions',
                       help='Replicate only given partitions. '
-                           'Comma-separated list')
+                           'Comma-separated list. '
+                           'Only has effect if --once is used.')
     parser.add_option('-i', '--policies',
                       help='Replicate only given policy indices. '
-                           'Comma-separated list')
+                           'Comma-separated list. '
+                           'Only has effect if --once is used.')
     conf_file, options = parse_options(parser=parser, once=True)
     run_daemon(ObjectReplicator, conf_file, **options)
diff --git a/doc/manpages/swift-object-reconstructor.1 b/doc/manpages/swift-object-reconstructor.1
index b387a5900f..82560e6af1 100644
--- a/doc/manpages/swift-object-reconstructor.1
+++ b/doc/manpages/swift-object-reconstructor.1
@@ -37,11 +37,12 @@ reconstruction before it has the correct data to push to the other node.
 Show this help message and exit
 .TP
 \fB\-d\fR \fIDEVICES\fR, \fB\-\-devices\fR=\fIDEVICES\fR
-Reconstruct only given devices. Comma\-separated list
+Reconstruct only given devices. Comma\-separated list. Only has effect if
+\-\-once is used.
 .TP
 \fB\-p\fR \fIPARTITIONS\fR, \fB\-\-partitions\fR=\fIPARTITIONS\fR
 Reconstruct only given partitions. Comma\-separated
-list
+list. Only has effect if \-\-once is used.
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
 Log to console
@@ -52,9 +53,9 @@ Only run one pass of daemon
 
 .SH DOCUMENTATION
 .LP
-More in depth documentation in regards to 
+More in depth documentation in regards to
 .BI swift\-object\-reconstructor
-and also about OpenStack Swift as a whole can be found at 
+and also about OpenStack Swift as a whole can be found at
 .BI http://docs.openstack.org/developer/swift/index.html
-and 
+and
 .BI http://docs.openstack.org
diff --git a/doc/manpages/swift-object-replicator.1 b/doc/manpages/swift-object-replicator.1
index 6d765f5ad2..c3937a6c48 100644
--- a/doc/manpages/swift-object-replicator.1
+++ b/doc/manpages/swift-object-replicator.1
@@ -41,22 +41,29 @@ from the system. When an object item is deleted a tombstone is set as the latest
 version of the item. The replicator will see the tombstone and ensure that the item
 is removed from the entire system.
 
-The options are as follows:
-
-.RS 4
-.PD 0
-.IP "-v"
-.IP "--verbose"
-.RS 4
-.IP "log to console"
-.RE
-.IP "-o"
-.IP "--once"
-.RS 4
-.IP "only run one pass of daemon"
-.RE
-.PD
-.RE
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show this help message and exit
+.TP
+\fB\-d\fR \fIDEVICES\fR, \fB\-\-devices\fR=\fIDEVICES\fR
+Replicate only given devices. Comma\-separated list. Only has effect if
+\-\-once is used.
+.TP
+\fB\-p\fR \fIPARTITIONS\fR, \fB\-\-partitions\fR=\fIPARTITIONS\fR
+Replicate only given partitions. Comma\-separated
+list. Only has effect if \-\-once is used.
+.TP
+\fB\-i\fR \fIPOLICIES\fR, \fB\-\-policies\fR=\fIPOLICIES\fR
+Replicate only given policy indices. Comma\-separated list. Only has effect if
+\-\-once is used.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Log to console
+.TP
+\fB\-o\fR, \fB\-\-once\fR
+Only run one pass of daemon
+.PP
 
 
 .SH DOCUMENTATION
diff --git a/doc/source/object.rst b/doc/source/object.rst
index 344db0b8b7..73e9ee0eae 100644
--- a/doc/source/object.rst
+++ b/doc/source/object.rst
@@ -44,6 +44,16 @@ Object Replicator
     :undoc-members:
     :show-inheritance:
 
+.. _object-reconstructor:
+
+Object Reconstructor
+====================
+
+.. automodule:: swift.obj.reconstructor
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 .. _object-server:
 
 Object Server