[2.6] More consistent Docker unit parsing (#44521)

* More consistent Docker unit parsing (#16748)

* Docker: Convert units for kernel_memory

Other memory arguments already use human_to_bytes to convert the
units.  This change makes the behavior more consistent.

* Update Docker unit parsing documentation

This explains the units more precisely and makes the documentation
more consistent.

This fixes #16526.

* Add changelog entry.

changelogs/fragments/16748-docker_container-memory.yaml

@@ -0,0 +1,5 @@
+bugfixes:
+- "docker_container: makes unit parsing for memory sizes more consistent, and
+   fixes idempotency problem when ``kernel_memory`` is set (see
+   https://github.com/ansible/ansible/pull/16748 and
+   https://github.com/ansible/ansible/issues/42692)"

lib/ansible/modules/cloud/docker/docker_container.py

@@ -164,8 +164,10 @@ options:
       - Override default signal used to kill a running container.
   kernel_memory:
     description:
-      - "Kernel memory limit (format: <number>[<unit>]). Number is a positive integer.
+      - "Kernel memory limit (format: C(<number>[<unit>])). Number is a positive integer.
-        Unit can be one of b, k, m, or g. Minimum is 4M."
+        Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
+        C(T) (tebibyte), or C(P) (pebibyte). Minimum is C(4M)."
+      - Omitting the unit defaults to bytes.
     default: 0
   labels:
      description:
@@ -189,18 +191,24 @@ options:
       - Container MAC address (e.g. 92:d0:c6:0a:29:33)
   memory:
     description:
-      - "Memory limit (format: <number>[<unit>]). Number is a positive integer.
+      - "Memory limit (format: C(<number>[<unit>])). Number is a positive integer.
-        Unit can be one of b, k, m, or g"
+        Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
+        C(T) (tebibyte), or C(P) (pebibyte)."
+      - Omitting the unit defaults to bytes.
     default: '0'
   memory_reservation:
     description:
-      - "Memory soft limit (format: <number>[<unit>]). Number is a positive integer.
+      - "Memory soft limit (format: C(<number>[<unit>])). Number is a positive integer.
-        Unit can be one of b, k, m, or g"
+        Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
+        C(T) (tebibyte), or C(P) (pebibyte)."
+      - Omitting the unit defaults to bytes.
     default: 0
   memory_swap:
     description:
-      - Total memory limit (memory + swap, format:<number>[<unit>]).
+      - "Total memory limit (memory + swap, format: C(<number>[<unit>])).
-        Number is a positive integer. Unit can be one of b, k, m, or g.
+        Number is a positive integer. Unit can be C(B) (byte), C(K) (kibibyte, 1024B),
+        C(M) (mebibyte), C(G) (gibibyte), C(T) (tebibyte), or C(P) (pebibyte)."
+      - Omitting the unit defaults to bytes.
     default: 0
   memory_swappiness:
     description:
@@ -310,9 +318,10 @@ options:
     default: 0
   shm_size:
     description:
-      - Size of `/dev/shm`. The format is `<number><unit>`. `number` must be greater than `0`.
+      - "Size of C(/dev/shm) (format: C(<number>[<unit>])). Number is positive integer.
-        Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes).
+        Unit can be C(B) (byte), C(K) (kibibyte, 1024B), C(M) (mebibyte), C(G) (gibibyte),
-      - Omitting the unit defaults to bytes. If you omit the size entirely, the system uses `64m`.
+        C(T) (tebibyte), or C(P) (pebibyte)."
+      - Omitting the unit defaults to bytes. If you omit the size entirely, the system uses C(64M).
   security_opts:
     description:
       - List of security options in the form of C("label:user:User")
@@ -625,6 +634,7 @@ except:
 
 
 REQUIRES_CONVERSION_TO_BYTES = [
+    'kernel_memory',
     'memory',
     'memory_reservation',
     'memory_swap',