diff --git a/doc/manpages/proxy-server.conf.5 b/doc/manpages/proxy-server.conf.5
index 26d639c12c..4f4ac8be7f 100644
--- a/doc/manpages/proxy-server.conf.5
+++ b/doc/manpages/proxy-server.conf.5
@@ -1026,26 +1026,42 @@ Set to the number of nodes to contact for a normal request. You can use '* repli
at the end to have it use the number given times the number of
replicas for the ring being used for the request. The default is '2 * replicas'.
.IP \fBread_affinity\fR
-Which backend servers to prefer on reads. Format is r<N> for region
-N or r<N>z<M> for region N, zone M. The value after the equals is
-the priority; lower numbers are higher priority.
-Default is empty, meaning no preference.
-Example: first read from region 1 zone 1, then region 1 zone 2, then anything in region 2, then everything else:
-read_affinity = r1z1=100, r1z2=200, r2=300
+Specifies which backend servers to prefer on reads. Format is a comma
+separated list of affinity descriptors of the form <selection>=<priority>.
+The <selection> may be r<N> for selecting nodes in region N or r<N>z<M> for
+selecting nodes in region N, zone M. The <priority> value should be a whole
+number that represents the priority to be given to the selection; lower numbers
+are higher priority. Default is empty, meaning no preference.
+
+Example: first read from region 1 zone 1, then region 1 zone 2, then anything
+in region 2, then everything else:
+
+.PD 0
+.RS 10
+.IP "read_affinity = r1z1=100, r1z2=200, r2=300"
+.RE
+.PD
.IP \fBwrite_affinity\fR
-Which backend servers to prefer on writes. Format is r<N> for region
-N or r<N>z<M> for region N, zone M. If this is set, then when
-handling an object PUT request, some number (see setting
-write_affinity_node_count) of local backend servers will be tried
-before any nonlocal ones. Default is empty, meaning no preference.
+Specifies which backend servers to prefer on writes. Format is a comma
+separated list of affinity descriptors of the form r<N> for region N or
+r<N>z<M> for region N, zone M. If this is set, then when handling an object
+PUT request, some number (see setting write_affinity_node_count) of local
+backend servers will be tried before any nonlocal ones. Default is empty,
+meaning no preference.
+
Example: try to write to regions 1 and 2 before writing to any other
nodes:
+
+.PD 0
+.RS 10
write_affinity = r1, r2
+.RE
+.PD
.IP \fBwrite_affinity_node_count\fR
-The number of local (as governed by the write_affinity setting)
-nodes to attempt to contact first, before any non-local ones. You
-can use '* replicas' at the end to have it use the number given
-times the number of replicas for the ring being used for the
+The number of local (as governed by the write_affinity setting) nodes to
+attempt to contact first on writes, before any non-local ones. The value
+should be an integer number, or use '* replicas' at the end to have it use
+the number given times the number of replicas for the ring being used for the
request. The default is '2 * replicas'.
.IP \fBswift_owner_headers\fR
These are the headers whose values will only be shown to swift_owners. The
diff --git a/doc/source/deployment_guide.rst b/doc/source/deployment_guide.rst
index 16437737c1..8ee2f46da6 100644
--- a/doc/source/deployment_guide.rst
+++ b/doc/source/deployment_guide.rst
@@ -1794,6 +1794,38 @@ ionice_priority None I/O scheduling priority of server
I/O priority of the process. Work
only with ionice_class.
Ignored if IOPRIO_CLASS_IDLE is set.
+read_affinity None Specifies which backend servers to
+ prefer on reads; used in conjunction
+ with the sorting_method option being
+ set to 'affinity'. Format is a comma
+ separated list of affinity descriptors
+ of the form <selection>=<priority>.
+ The <selection> may be r<N> for
+ selecting nodes in region N or
+ r<N>z<M> for selecting nodes in
+ region N, zone M. The <priority>
+ value should be a whole number
+ that represents the priority to
+ be given to the selection; lower
+ numbers are higher priority.
+ Default is empty, meaning no
+ preference.
+write_affinity None Specifies which backend servers to
+ prefer on writes. Format is a comma
+ separated list of affinity
+ descriptors of the form r<N> for
+ region N or r<N>z<M> for region N,
+ zone M. Default is empty, meaning no
+ preference.
+write_affinity_node_count 2 * replicas The number of local (as governed by
+ the write_affinity setting) nodes to
+ attempt to contact first on writes,
+ before any non-local ones. The value
+ should be an integer number, or use
+ '* replicas' at the end to have it
+ use the number given times the number
+ of replicas for the ring being used
+ for the request.
============================ =============== =====================================
[tempauth]
diff --git a/etc/proxy-server.conf-sample b/etc/proxy-server.conf-sample
index 72084dccb1..97f613725b 100644
--- a/etc/proxy-server.conf-sample
+++ b/etc/proxy-server.conf-sample
@@ -200,9 +200,12 @@ use = egg:swift#proxy
# replicas for the ring being used for the request.
# request_node_count = 2 * replicas
#
-# Which backend servers to prefer on reads. Format is r<N> for region
-# N or r<N>z<M> for region N, zone M. The value after the equals is
-# the priority; lower numbers are higher priority.
+# Specifies which backend servers to prefer on reads. Format is a comma
+# separated list of affinity descriptors of the form <selection>=<priority>.
+# The <selection> may be r<N> for selecting nodes in region N or r<N>z<M> for
+# selecting nodes in region N, zone M. The <priority> value should be a whole
+# number that represents the priority to be given to the selection; lower
+# numbers are higher priority.
#
# Example: first read from region 1 zone 1, then region 1 zone 2, then
# anything in region 2, then everything else:
@@ -210,11 +213,11 @@ use = egg:swift#proxy
# Default is empty, meaning no preference.
# read_affinity =
#
-# Which backend servers to prefer on writes. Format is r<N> for region
-# N or r<N>z<M> for region N, zone M. If this is set, then when
-# handling an object PUT request, some number (see setting
-# write_affinity_node_count) of local backend servers will be tried
-# before any nonlocal ones.
+# Specifies which backend servers to prefer on writes. Format is a comma
+# separated list of affinity descriptors of the form r<N> for region N or
+# r<N>z<M> for region N, zone M. If this is set, then when handling an object
+# PUT request, some number (see setting write_affinity_node_count) of local
+# backend servers will be tried before any nonlocal ones.
#
# Example: try to write to regions 1 and 2 before writing to any other
# nodes:
@@ -222,10 +225,10 @@ use = egg:swift#proxy
# Default is empty, meaning no preference.
# write_affinity =
#
-# The number of local (as governed by the write_affinity setting)
-# nodes to attempt to contact first, before any non-local ones. You
-# can use '* replicas' at the end to have it use the number given
-# times the number of replicas for the ring being used for the
+# The number of local (as governed by the write_affinity setting) nodes to
+# attempt to contact first on writes, before any non-local ones. The value
+# should be an integer number, or use '* replicas' at the end to have it use
+# the number given times the number of replicas for the ring being used for the
# request.
# write_affinity_node_count = 2 * replicas
#