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

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

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.