docs: rewrite reference docs for --stop-signal and --stop-timeout

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
(cherry picked from commit 16466f1ce6)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

docs/reference/builder.md

@@ -2171,9 +2171,14 @@ ONBUILD RUN /usr/local/bin/python-build --dir /app/src
 STOPSIGNAL signal
 ```
 
-The `STOPSIGNAL` instruction sets the system call signal that will be sent to the container to exit.
+The `STOPSIGNAL` instruction sets the system call signal that will be sent to the
-This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9,
+container to exit. This signal can be a signal name in the format `SIG<NAME>`,
-or a signal name in the format SIGNAME, for instance SIGKILL.
+for instance `SIGKILL`, or an unsigned number that matches a position in the
+kernel's syscall table, for instance `9`. The default is `SIGTERM` if not
+defined.
+
+The image's default stopsignal can be overridden per container, using the
+`--stop-signal` flag on `docker run` and `docker create`.
 
 ## HEALTHCHECK
 

docs/reference/commandline/create.md

@@ -109,7 +109,7 @@ Options:
                                       Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes),
                                       or `g` (gigabytes). If you omit the unit, the system uses bytes.
       --stop-signal string            Signal to stop a container (default "SIGTERM")
-      --stop-timeout=10               Timeout (in seconds) to stop a container
+      --stop-timeout int              Timeout (in seconds) to stop a container
       --storage-opt value             Storage driver options for the container (default [])
       --sysctl value                  Sysctl options (default map[])
       --tmpfs value                   Mount a tmpfs directory (default [])

docs/reference/commandline/kill.md

@@ -20,8 +20,18 @@ Options:
 
 The `docker kill` subcommand kills one or more containers. The main process
 inside the container is sent `SIGKILL` signal (default), or the signal that is
-specified with the `--signal` option. You can kill a container using the
+specified with the `--signal` option. You can reference a container by its
-container's ID, ID-prefix, or name.
+ID, ID-prefix, or name.
+
+The `--signal` (or `-s` shorthand) flag sets the system call signal that is sent
+to the container. This signal can be a signal name in the format `SIG<NAME>`, for
+instance `SIGINT`, or an unsigned number that matches a position in the kernel's
+syscall table, for instance `2`.
+
+While the default (`SIGKILL`) signal will terminate the container, the signal
+set through `--signal` may be non-terminal, depending on the container's main
+process. For example, the `SIGHUP` signal in most cases will be non-terminal,
+and the container will continue running after receiving the signal.
 
 > **Note**
 >
@@ -32,16 +42,16 @@ container's ID, ID-prefix, or name.
 ## Examples
 
 
-### Send a KILL signal  to a container
+### Send a KILL signal to a container
 
-The following example sends the default `KILL` signal to the container named
+The following example sends the default `SIGKILL` signal to the container named
 `my_container`:
 
 ```bash
 $ docker kill my_container
 ```
 
-### Send a custom signal  to a container
+### Send a custom signal to a container
 
 The following example sends a `SIGHUP` signal to the container named
 `my_container`:

docs/reference/commandline/run.md

@@ -120,7 +120,7 @@ Options:
                                       or `g` (gigabytes). If you omit the unit, the system uses bytes.
       --sig-proxy                     Proxy received signals to the process (default true)
       --stop-signal string            Signal to stop a container (default "SIGTERM")
-      --stop-timeout=10               Timeout (in seconds) to stop a container
+      --stop-timeout int              Timeout (in seconds) to stop a container
       --storage-opt value             Storage driver options for the container (default [])
       --sysctl value                  Sysctl options (default map[])
       --tmpfs value                   Mount a tmpfs directory (default [])
@@ -745,9 +745,12 @@ the three processes quota set for the `daemon` user.
 
 ### Stop container with signal (--stop-signal)
 
-The `--stop-signal` flag sets the system call signal that will be sent to the container to exit.
+The `--stop-signal` flag sets the system call signal that will be sent to the
-This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9,
+container to exit. This signal can be a signal name in the format `SIG<NAME>`,
-or a signal name in the format SIGNAME, for instance SIGKILL.
+for instance `SIGKILL`, or an unsigned number that matches a position in the
+kernel's syscall table, for instance `9`.
+
+The default is `SIGTERM` if not specified.
 
 ### Optional security options (--security-opt)
 
@@ -756,8 +759,16 @@ The `credentialspec` must be in the format `file://spec.txt` or `registry://keyn
 
 ### Stop container with timeout (--stop-timeout)
 
-The `--stop-timeout` flag sets the timeout (in seconds) that a pre-defined (see `--stop-signal`) system call
+The `--stop-timeout` flag sets the number of seconds to wait for the container
-signal that will be sent to the container to exit. After timeout elapses the container will be killed with SIGKILL.
+to stop after sending the pre-defined (see `--stop-signal`) system call signal.
+If the container does not exit after the timeout elapses, it is forcibly killed
+with a `SIGKILL` signal.
+
+If `--stop-timeout` is set to `-1`, no timeout is applied, and the daemon will
+wait indefinitely for the container to exit.
+
+The default is determined by the daemon, and is 10 seconds for Linux containers,
+and 30 seconds for Windows containers.
 
 ### Specify isolation technology for container (--isolation)
 

man/Dockerfile.5.md

@@ -183,6 +183,18 @@ A Dockerfile is similar to a Makefile.
 
   To display an image's labels, use the `docker inspect` command.
 
+**STOPSIGNAL**
+
+  -- `STOPSIGNAL <signal>`
+  The **STOPSIGNAL** instruction sets the system call signal that will be sent
+  to the container to exit. This signal can be a signal name in the format
+  **SIG<NAME>**, for instance **SIGKILL**, or an unsigned number that matches a
+  position in the kernel's syscall table, for instance **9**. The default is
+  **SIGTERM** if not defined.
+
+  The image's default stopsignal can be overridden per container, using the
+  **--stop-signal** flag on **docker-run(1)** and **docker-create(1)**.
+
 **EXPOSE**
   -- `EXPOSE <port> [<port>...]`
   The **EXPOSE** instruction informs Docker that the container listens on the

man/docker-run.1.md

@@ -622,10 +622,26 @@ incompatible with any restart policy other than `none`.
    Under these conditions, user can pass any size less than the backing fs size.
 
 **--stop-signal**=*SIGTERM*
-  Signal to stop a container. Default is SIGTERM.
+   Signal to stop the container. Default is SIGTERM.
 
-**--stop-timeout**=*10*
+   The `--stop-signal` flag sets the system call signal that will be sent to the
-  Timeout (in seconds) to stop a container. Default is 10.
+   container to exit. This signal can be a signal name in the format `SIG<NAME>`,
+   for instance `SIGKILL`, or an unsigned number that matches a position in the
+   kernel's syscall table, for instance `9`.
+
+**--stop-timeout**
+  Timeout (in seconds) to stop a container, or **-1** to disable timeout.
+
+  The `--stop-timeout` flag sets the number of seconds to wait for the container
+  to stop after sending the pre-defined (see `--stop-signal`) system call signal.
+  If the container does not exit after the timeout elapses, it is forcibly killed
+  with a `SIGKILL` signal.
+
+  If `--stop-timeout` is set to **-1**, no timeout is applied, and the daemon will
+  wait indefinitely for the container to exit.
+
+  The default is determined by the daemon, and 10 seconds for Linux containers,
+  and 30 seconds for Windows containers.
 
 **--shm-size**=""
    Size of `/dev/shm`. The format is `<number><unit>`.