Merge pull request #24535 from thaJeztah/minor-docs-fixup

docs: cleanup docker update docs

docs/reference/commandline/update.md

@@ -31,44 +31,25 @@ Options:
 ```
 
 The `docker update` command dynamically updates container configuration.
-You can use this command to prevent containers from consuming too many resources
-from their Docker host.  With a single command, you can place limits on
-a single container or on many. To specify more than one container, provide
-space-separated list of container names or IDs.
+You can use this command to prevent containers from consuming too many 
+resources from their Docker host.  With a single command, you can place 
+limits on a single container or on many. To specify more than one container,
+provide space-separated list of container names or IDs.
 
-With the exception of the `--kernel-memory` value, you can specify these
+With the exception of the `--kernel-memory` option, you can specify these
 options on a running or a stopped container. You can only update
 `--kernel-memory` on a stopped container or on a running container with
-kernel memory initialized. For example, if you started a container with
-command:
-
-    # docker run -ti --name test --kernel-memory 50M ubuntu bash
-
-You can update kernel memory of this running container:
-
-    # docker update --kernel-memory 80M test
-
-If you started a container without kernel memory initialized:
-
-    # docker run -ti --name test2 --memory 300M ubuntu bash
-
-Update kernel memory of running container `test2` will fail, you can only
-stop the container and update kernel memory then. The next time you
-restart it, the container uses the new value.
-
-Another configuration you can change with this command is restart policy,
-new restart policy will take effect instantly after you run `docker update`
-on a container.
+kernel memory initialized.
 
 ## EXAMPLES
 
 The following sections illustrate ways to use this command.
 
-### Update a container with cpu-shares=512
+### Update a container's cpu-shares
 
 To limit a container's cpu-shares to 512, first identify the container
-name or ID. You can use **docker ps** to find these values. You can also
-use the ID returned from the **docker run** command.  Then, do the following:
+name or ID. You can use `docker ps` to find these values. You can also
+use the ID returned from the `docker run` command.  Then, do the following:
 
 ```bash
 $ docker update --cpu-shares 512 abebf7571666
@@ -82,9 +63,44 @@ To update multiple resource configurations for multiple containers:
 $ docker update --cpu-shares 512 -m 300M abebf7571666 hopeful_morse
 ```
 
+### Update a container's kernel memory constraints
+
+You can update a container's kernel memory limit using the `--kernel-memory`
+option. This option can be updated on a running container only if the container
+was started with `--kernel-memory`. If the container was started *without*
+`--kernel-memory` you need to stop the container before updating kernel memory.
+
+For example, if you started a container with this command:
+
+```bash
+$ docker run -dit --name test --kernel-memory 50M ubuntu bash
+```
+
+You can update kernel memory while the container is running:
+
+```bash
+$ docker update --kernel-memory 80M test
+```
+
+If you started a container *without* kernel memory initialized:
+
+```bash
+$ docker run -dit --name test2 --memory 300M ubuntu bash
+```
+
+Update kernel memory of running container `test2` will fail. You need to stop
+the container before updating the `--kernel-memory` setting. The next time you
+start it, the container uses the new value.
+
+
 ### Update a container's restart policy
 
+You can change a container's restart policy on a running container. The new
+restart policy takes effect instantly after you run `docker update` on a
+container.
+
 To update restart policy for one or more containers:
+
 ```bash
 $ docker update --restart=on-failure:3 abebf7571666 hopeful_morse
 ```

man/docker-update.1.md

@@ -22,37 +22,19 @@ CONTAINER [CONTAINER...]
 
 # DESCRIPTION
 
-The `docker update` command dynamically updates container configuration.
-you can Use this command to prevent containers from consuming too many 
+The **docker update** command dynamically updates container configuration.
+You can use this command to prevent containers from consuming too many 
 resources from their Docker host.  With a single command, you can place 
 limits on a single container or on many. To specify more than one container,
 provide space-separated list of container names or IDs.
 
-With the exception of the `--kernel-memory` value, you can specify these
+With the exception of the **--kernel-memory** option, you can specify these
 options on a running or a stopped container. You can only update
-`--kernel-memory` on a stopped container or on a running container with
-kernel memory initialized. For example, if you started a container with
-command:
-
-    # docker run -ti --name test --kernel-memory 50M ubuntu bash
-
-You can update kernel memory of this running container:
-
-    # docker update --kernel-memory 80M test
-
-If you started a container without kernel memory initialized:
-
-    # docker run -ti --name test2 --memory 300M ubuntu bash
-
-Update kernel memory of running container `test2` will fail, you can only
-stop the container and update kernel memory then. The next time you
-restart it, the container uses the new value.
-
-Another configuration you can change with this command is restart policy,
-new restart policy will take effect instantly after you run `docker update`
-on a container.
+**--kernel-memory** on a stopped container or on a running container with
+kernel memory initialized.
 
 # OPTIONS
+
 **--blkio-weight**=0
    Block IO weight (relative weight) accepts a weight value between 10 and 1000.
 
@@ -77,9 +59,9 @@ on a container.
 **--kernel-memory**=""
    Kernel memory limit (format: `<number>[<unit>]`, where unit = b, k, m or g)
 
-   Note that you can not update kernel memory to a running container if the container
-is started without kernel memory initialized, in this case, it can only be updated
-after it's stopped, and affect after it's started.
+   Note that you can not update kernel memory on a running container if the container
+   is started without kernel memory initialized, in this case, it can only be updated
+   after it's stopped. The new setting takes effect when the container is started.
 
 **-m**, **--memory**=""
    Memory limit (format: <number><optional unit>, where unit = b, k, m or g)
@@ -97,7 +79,7 @@ after it's stopped, and affect after it's started.
 
 The following sections illustrate ways to use this command.
 
-### Update a container with cpu-shares=512
+### Update a container's cpu-shares
 
 To limit a container's cpu-shares to 512, first identify the container
 name or ID. You can use **docker ps** to find these values. You can also
@@ -115,9 +97,43 @@ To update multiple resource configurations for multiple containers:
 $ docker update --cpu-shares 512 -m 300M abebf7571666 hopeful_morse
 ```
 
+### Update a container's kernel memory constraints
+
+You can update a container's kernel memory limit using the **--kernel-memory**
+option. This option can be updated on a running container only if the container
+was started with **--kernel-memory**. If the container was started *without*
+**--kernel-memory** you need to stop the container before updating kernel memory.
+
+For example, if you started a container with this command:
+
+```bash
+$ docker run -dit --name test --kernel-memory 50M ubuntu bash
+```
+
+You can update kernel memory while the container is running:
+
+```bash
+$ docker update --kernel-memory 80M test
+```
+
+If you started a container *without* kernel memory initialized:
+
+```bash
+$ docker run -dit --name test2 --memory 300M ubuntu bash
+```
+
+Update kernel memory of running container `test2` will fail. You need to stop
+the container before updating the **--kernel-memory** setting. The next time you
+start it, the container uses the new value.
+
 ### Update a container's restart policy
 
+You can change a container's restart policy on a running container. The new
+restart policy takes effect instantly after you run `docker update` on a
+container.
+
 To update restart policy for one or more containers:
+
 ```bash
 $ docker update --restart=on-failure:3 abebf7571666 hopeful_morse
 ```