From 068a56eb97f7b8a0522f94eec7b66a95fff80a1d Mon Sep 17 00:00:00 2001
From: Victoria Bialas <victoria.bialas@docker.com>
Date: Thu, 18 Feb 2016 17:49:28 -0800
Subject: [PATCH] corrected description of network aliases, added real-world
 example per #2907

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>
---
 docs/compose-file.md | 41 ++++++++++++++++++++++++++++++++++-------
 1 file changed, 34 insertions(+), 7 deletions(-)

diff --git a/docs/compose-file.md b/docs/compose-file.md
index 6441297f..77c69734 100644
--- a/docs/compose-file.md
+++ b/docs/compose-file.md
@@ -477,15 +477,13 @@ Networks to join, referencing entries under the
 
 #### aliases
 
-Aliases (alternative hostnames) for this service on the network. Other servers
-on the network can use either the service name or this alias to connect to
-this service.  Since `alias` is network-scoped:
+Aliases (alternative hostnames) for this service on the network. Other containers on the same network can use either the service name or this alias to connect to one of the service's containers.  
 
-  * the same service can have different aliases when connected to another
-    network.
-  * it is allowable to configure the same alias name to multiple containers
-    (services) on the same network.
+Since `aliases` is network-scoped, the same service can have different aliases on different networks.
 
+> **Note**: A network-wide alias can be shared by multiple containers, and even by multiple services. If it is, then exactly which container the name will resolve to is not guaranteed.
+
+The general format is shown here.
 
     networks:
       some-network:
@@ -496,6 +494,35 @@ this service.  Since `alias` is network-scoped:
         aliases:
           - alias2
 
+In the example below, three services are provided (`web`, `worker`, and `db`), along with two networks (`new` and `legacy`). The `db` service is reachable at the hostname `db` or `database` on the `new` network, and at `db` or `mysql` on the legacy network.
+
+    version: 2
+
+    services:
+      web:
+        build: ./web
+        networks:
+          - new
+
+      worker:
+        build: ./worker
+        networks:
+        - legacy
+
+      db:
+        image: mysql
+        networks:
+          new:
+            aliases:
+              - database
+          legacy:
+            aliases:
+              - mysql
+
+    networks:
+      new:
+      legacy:
+
 ### pid
 
     pid: "host"