update docs for memory and memoryswap

Signed-off-by: Qiang Huang <h.huangqiang@huawei.com>

docs/man/docker-create.1.md

@@ -27,6 +27,7 @@ docker-create - Create a new container
 [**--link**[=*[]*]]
 [**--lxc-conf**[=*[]*]]
 [**-m**|**--memory**[=*MEMORY*]]
+[**--memory-swap**[=*MEMORY-SWAP*]]
 [**--mac-address**[=*MAC-ADDRESS*]]
 [**--name**[=*NAME*]]
 [**--net**[=*"bridge"*]]
@@ -110,6 +111,18 @@ IMAGE [COMMAND] [ARG...]
 **-m**, **--memory**=""
    Memory limit (format: <number><optional unit>, where unit = b, k, m or g)
 
+   Allows you to constrain the memory available to a container. If the host
+supports swap memory, then the **-m** memory setting can be larger than physical
+RAM. If a limit of 0 is specified (not using **-m**), the container's memory is
+not limited. The actual limit may be rounded up to a multiple of the operating
+system's page size (the value would be very large, that's millions of trillions).
+
+**--memory-swap**=""
+   Total memory limit (memory + swap)
+
+   Set `-1` to disable swap (format: <number><optional unit>, where unit = b, k, m or g).
+This value should always larger than **-m**, so you should alway use this with **-m**.
+
 **--mac-address**=""
    Container MAC address (e.g. 92:d0:c6:0a:29:33)
 
@@ -142,7 +155,7 @@ IMAGE [COMMAND] [ARG...]
    Give extended privileges to this container. The default is *false*.
 
 **--read-only**=*true*|*false*
-    Mount the container's root filesystem as read only.
+   Mount the container's root filesystem as read only.
 
 **--restart**=""
    Restart policy to apply when a container exits (no, on-failure[:max-retry], always)

docs/man/docker-run.1.md

@@ -186,16 +186,16 @@ which interface and port to use.
    Memory limit (format: <number><optional unit>, where unit = b, k, m or g)
 
    Allows you to constrain the memory available to a container. If the host
-supports swap memory, then the -m memory setting can be larger than physical
-RAM. If a limit of 0 is specified, the container's memory is not limited. The
-actual limit may be rounded up to a multiple of the operating system's page
-size, if it is not already. The memory limit should be formatted as follows:
-`<number><optional unit>`, where unit = b, k, m or g.
+supports swap memory, then the **-m** memory setting can be larger than physical
+RAM. If a limit of 0 is specified (not using **-m**), the container's memory is
+not limited. The actual limit may be rounded up to a multiple of the operating
+system's page size (the value would be very large, that's millions of trillions).
 
 **--memory-swap**=""
-    Total memory usage (memory + swap)
+   Total memory limit (memory + swap)
 
-    Set '-1' to disable swap (format: <number><optional unit>, where unit = b, k, m or g)
+   Set `-1` to disable swap (format: <number><optional unit>, where unit = b, k, m or g).
+This value should always larger than **-m**, so you should alway use this with **-m**.
 
 **--mac-address**=""
    Container MAC address (e.g. 92:d0:c6:0a:29:33)

docs/sources/reference/api/docker_remote_api_v1.17.md

@@ -177,7 +177,8 @@ Json Parameters:
       for the container.
 -   **User** - A string value containg the user to use inside the container.
 -   **Memory** - Memory limit in bytes.
--   **MemorySwap**- Total memory usage (memory + swap); set `-1` to disable swap.
+-   **MemorySwap**- Total memory limit (memory + swap); set `-1` to disable swap,
+      always use this with `memory`, and make the value larger than `memory`.
 -   **CpuShares** - An integer value containing the CPU Shares for container
       (ie. the relative weight vs othercontainers).
     **CpuSet** - String value containg the cgroups Cpuset to use.

docs/sources/reference/run.md

@@ -310,13 +310,26 @@ The operator can also adjust the performance parameters of the
 container:
 
     -m="": Memory limit (format: <number><optional unit>, where unit = b, k, m or g)
+    -memory-swap="": Total memory limit (memory + swap, format: <number><optional unit>, where unit = b, k, m or g)
     -c=0 : CPU shares (relative weight)
 
-The operator can constrain the memory available to a container easily
-with `docker run -m`. If the host supports swap memory, then the `-m`
-memory setting can be larger than physical RAM.
+We have four ways to set memory usage:
+ - memory=inf, memory-swap=inf (not specify any of them)
+   There is no memory limit, you can use as much as you want.
 
-Similarly the operator can increase the priority of this container with
+ - memory=L<inf, memory-swap=inf (specify memory and set memory-swap as `-1`)
+   It is not allowed to use more than L bytes of memory, but use as much swap
+   as you want (only if the host supports swap memory).
+
+ - memory=L<inf, memory-swap=2*L (specify memory without memory-swap)
+   It is not allowed to use more than L bytes of memory, swap *plus* memory
+   usage is double of that.
+
+ - memory=L<inf, memory-swap=S<inf, L<=S (specify both memory and memory-swap)
+   It is not allowed to use more than L bytes of memory, swap *plus* memory
+   usage is limited by S.
+
+The operator can increase the priority of this container with
 the `-c` option. By default, all containers run at the same priority and
 get the same proportion of CPU cycles, but you can tell the kernel to
 give more shares of CPU time to one or more containers when you start