Tell users about how VOLUME initializes the new mount point/volume

Signed-off-by: Doug Davis <dug@us.ibm.com>

docs/man/docker-run.1.md

@@ -325,16 +325,20 @@ read-write. See examples.
 **--volumes-from**=[]
    Mount volumes from the specified container(s)
 
-   Will mount volumes from the specified container identified by container-id.
-Once a volume is mounted in a one container it can be shared with other
-containers using the **--volumes-from** option when running those other
-containers. The volumes can be shared even if the original container with the
-mount is not running.
+   Mounts already mounted volumes from a source container onto another
+   container. You must supply the source's container-id. To share 
+   a volume, use the **--volumes-from** option when running
+   the target container. You can share volumes even if the source container 
+   is not running.
 
-   The container ID may be optionally suffixed with :ro or
-:rw to mount the volumes in read-only or read-write mode, respectively. By
-default, the volumes are mounted in the same mode (read write or read only) as
-the reference container.
+   By default, Docker mounts the volumes in the same mode (read-write or 
+   read-only) as it is mounted in the source container. Optionally, you 
+   can change this by suffixing the container-id with either the `:ro` or 
+   `:rw ` keyword.
+
+   If the location of the volume from the source container overlaps with
+   data residing on a target container, then the volume hides
+   that data on the target.
 
 **-w**, **--workdir**=""
    Working directory inside the container

docs/sources/reference/builder.md

@@ -777,14 +777,28 @@ If you then run `docker stop test`, the container will not exit cleanly - the
 
     VOLUME ["/data"]
 
-The `VOLUME` instruction will create a mount point with the specified name
-and mark it as holding externally mounted volumes from native host or other
+The `VOLUME` instruction creates a mount point with the specified name
+and marks it as holding externally mounted volumes from native host or other
 containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain
 string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log
 /var/db`.  For more information/examples and mounting instructions via the
-Docker client, refer to [*Share Directories via Volumes*](/userguide/dockervolumes/#volume)
+Docker client, refer to 
+[*Share Directories via Volumes*](/userguide/dockervolumes/#volume)
 documentation.
 
+The `docker run` command initializes the newly created volume with any data 
+that exists at the specified location within the base image. For example, 
+consider the following Dockerfile snippet:
+
+    FROM ubuntu
+    RUN mkdir /myvol
+    RUN echo "hello world" > /myvol/greating
+    VOLUME /myvol
+
+This Dockerfile results in an image that causes `docker run`, to
+create a new mount point at `/myvol` and copy the  `greating` file 
+into the newly created volume.
+
 > **Note**:
 > The list is parsed as a JSON array, which means that
 > you must use double-quotes (") around words not single-quotes (').

docs/sources/userguide/dockervolumes.md

@@ -21,19 +21,21 @@ Docker.
 
 A *data volume* is a specially-designated directory within one or more
 containers that bypasses the [*Union File
-System*](/terms/layer/#union-file-system) to provide several useful features for
-persistent or shared data:
+System*](/terms/layer/#union-file-system). Data volumes provide several 
+useful features for persistent or shared data:
 
-- Volumes are initialized when a container is created
-- Data volumes can be shared and reused between containers
-- Changes to a data volume are made directly
-- Changes to a data volume will not be included when you update an image
-- Data volumes persist even if the container itself is deleted
+- Volumes are initialized when a container is created. If the container's
+  base image contains data at the specified mount point, that data is 
+  copied into the new volume.
+- Data volumes can be shared and reused among containers.
+- Changes to a data volume are made directly.
+- Changes to a data volume will not be included when you update an image.
+- Data volumes persist even if the container itself is deleted.
 
 Data volumes are designed to persist data, independent of the container's life 
-cycle. Docker will therefore *never* automatically delete volumes when you remove 
-a container, nor will it "garbage collect" volumes that are no longer referenced 
-by a container.
+cycle. Docker therefore *never* automatically delete volumes when you remove 
+a container, nor will it "garbage collect" volumes that are no longer 
+referenced by a container.
 
 ### Adding a data volume
 
@@ -132,6 +134,11 @@ And another:
 
     $ sudo docker run -d --volumes-from dbdata --name db2 training/postgres
 
+In this case, if the `postgres` image contained a directory called `/dbdata`
+then mounting the volumes from the `dbdata` container hides the
+`/dbdata` files from the `postgres` image. The result is only the files
+from the `dbdata` container are visible.
+
 You can use multiple `--volumes-from` parameters to bring together multiple data
 volumes from multiple containers.