update bind-mount docs

Signed-off-by: Akihiro Suda <[email protected]>

Author: AkihiroSuda

docs/reference/commandline/service_create.md

@@ -363,16 +363,34 @@ volumes in a service:
     <td></td>
     <td>
       <p>The Engine mounts binds and volumes <tt>read-write</tt> unless <tt>readonly</tt> option
-      is given when mounting the bind or volume.
+      is given when mounting the bind or volume. Note that setting <tt>readonly</tt> for a
+      bind-mount does not make its submounts <tt>readonly</tt>. See also <tt>bind-nonrecursive</tt>.
       <ul>
         <li><tt>true</tt> or <tt>1</tt> or no value: Mounts the bind or volume read-only.</li>
         <li><tt>false</tt> or <tt>0</tt>: Mounts the bind or volume read-write.</li>
       </ul></p>
     </td>
   </tr>
+</table>
+
+#### Options for Bind Mounts
+
+The following options can only be used for bind mounts (`type=bind`):
+
+
+<table>
+  <tr>
+    <th>Option</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><b>bind-propagation</b></td>
+    <td>
+      <p>See the description below.</p>
+    </td>
+  </tr>
   <tr>
     <td><b>consistency</b></td>
-    <td></td>
     <td>
       <p>The consistency requirements for the mount; one of
          <ul>
@@ -384,9 +402,23 @@ volumes in a service:
      </p>
     </td>
   </tr>
-</table>
+  <tr>
+    <td><b>bind-nonrecursive</b></td>
+    <td>
+      By default, submounts are recursively bind-mounted as well. However, this behavior can be confusing when a
+      bind mount is configured with <tt>readonly</tt> option, because submounts are not mounted as read-only.
+      Set <tt>bind-nonrecursive</tt> to disable recursive bind-mount.<br />
+
+      A value is optional:
 
-#### Bind Propagation
+      <ul>
+        <li><tt>true</tt> or <tt>1</tt>: Disables recursive bind-mount.</li>
+        <li><tt>false</tt> or <tt>0</tt>: Default if you do not provide a value. Enables recursive bind-mount.</li>
+      </ul>
+
+    </td>
+  </tr>
+</table>
 
 Bind propagation refers to whether or not mounts created within a given
 bind mount or named volume can be propagated to replicas of that mount. Consider

man/docker-run.1.md

@@ -446,12 +446,13 @@ according to RFC4862.
 
    * `src`, `source`: mount source spec for `bind` and `volume`. Mandatory for `bind`.
    * `dst`, `destination`, `target`: mount destination spec.
-   * `ro`, `read-only`: `true` or `false` (default).
+   * `ro`, `readonly`: `true` or `false` (default). Note that setting `readonly` for a bind mount does not make its submounts read-only. See also `bind-onrecursive`.
 
    Options specific to `bind`:
 
    * `bind-propagation`: `shared`, `slave`, `private`, `rshared`, `rslave`, or `rprivate`(default). See also `mount(2)`.
    * `consistency`: `consistent`(default), `cached`, or `delegated`. Currently, only effective for Docker for Mac.
+   * `bind-nonrecursive`: `true` or `false` (default). If set to `true`, submounts are not recursively bind-mounted. This option is useful for `readonly` bind mount.
 
    Options specific to `volume`: