Improve documentation (#278)

* Improve documentation.

* More fixes.

plugins/inventory/docker_machine.py

@@ -42,11 +42,14 @@ DOCUMENTATION = '''
                 - skip
             default: require
         running_required:
-            description: when true, hosts which Docker Machine indicates are in a state other than C(running) will be skipped.
+            description:
+                - When C(true), hosts which Docker Machine indicates are in a state other than C(running) will be skipped.
             type: bool
             default: yes
         verbose_output:
-            description: when true, include all available nodes metadata (e.g. Image, Region, Size) as a JSON object named C(docker_machine_node_attributes).
+            description:
+                - When C(true), include all available nodes metadata (for exmaple C(Image), C(Region), C(Size)) as a JSON object
+                  named C(docker_machine_node_attributes).
             type: bool
             default: yes
 '''
@@ -56,7 +59,7 @@ EXAMPLES = '''
 plugin: community.docker.docker_machine
 
 # Example using constructed features to create a group per Docker Machine driver
-# (https://docs.docker.com/machine/drivers/), e.g.:
+# (https://docs.docker.com/machine/drivers/), for example:
 #   $ docker-machine create --driver digitalocean ... mymachine
 #   $ ansible-inventory -i ./path/to/docker-machine.yml --host=mymachine
 #   {

plugins/inventory/docker_swarm.py

@@ -38,7 +38,7 @@ DOCUMENTATION = '''
             required: true
             aliases: [ docker_url ]
         verbose_output:
-            description: Toggle to (not) include all available nodes metadata (e.g. C(Platform), C(Architecture), C(OS),
+            description: Toggle to (not) include all available nodes metadata (for example C(Platform), C(Architecture), C(OS),
                          C(EngineVersion))
             type: bool
             default: yes
@@ -132,14 +132,14 @@ plugin: community.docker.docker_swarm
 docker_host: tcp://my-docker-host:2375
 strict: False
 keyed_groups:
-  # add e.g. x86_64 hosts to an arch_x86_64 group
+  # add for example x86_64 hosts to an arch_x86_64 group
   - prefix: arch
     key: 'Description.Platform.Architecture'
-  # add e.g. linux hosts to an os_linux group
+  # add for example linux hosts to an os_linux group
   - prefix: os
     key: 'Description.Platform.OS'
   # create a group per node label
-  # e.g. a node labeled w/ "production" ends up in group "label_production"
+  # for exomple a node labeled w/ "production" ends up in group "label_production"
   # hint: labels containing special characters will be converted to safe names
   - key: 'Spec.Labels'
     prefix: label

plugins/modules/docker_container.py

@@ -19,11 +19,11 @@ description:
 
 
 notes:
-  - For most config changes, the container needs to be recreated, i.e. the existing container has to be destroyed and
+  - For most config changes, the container needs to be recreated. This means that the existing container has to be destroyed and
     a new one created. This can cause unexpected data loss and downtime. You can use the I(comparisons) option to
     prevent this.
   - If the module needs to recreate the container, it will only use the options provided to the module to create the
-    new container (except I(image)). Therefore, always specify *all* options relevant to the container.
+    new container (except I(image)). Therefore, always specify B(all) options relevant to the container.
   - When I(restart) is set to C(true), the module will only restart the container if no config changes are detected.
 
 options:
@@ -81,7 +81,7 @@ options:
         or restarted if the module option contains a key which isn't present in the
         container's option, or if the value of a key present differs.
       - The wildcard option C(*) can be used to set one of the default values C(strict)
-        or C(ignore) to *all* comparisons which are not explicitly set to other values.
+        or C(ignore) to I(all) comparisons which are not explicitly set to other values.
       - See the examples for details.
     type: dict
   container_default_behavior:
@@ -296,7 +296,7 @@ options:
   env:
     description:
       - Dictionary of key,value pairs.
-      - Values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (e.g. C("true")) in order to avoid data loss.
+      - Values which might be parsed as numbers, booleans or other types by the YAML parser must be quoted (for example C("true")) in order to avoid data loss.
       - Please note that if you are passing values in with Jinja2 templates, like C("{{ value }}"), you need to add C(| string) to prevent Ansible to
         convert strings such as C("true") back to booleans. The correct way is to use C("{{ value | string }}").
     type: dict
@@ -383,7 +383,7 @@ options:
         container to requested configuration. The evaluation includes the image version. If the image
         version in the registry does not match the container, the container will be recreated. You can
         stop this behavior by setting I(ignore_image) to C(True).
-      - "*Warning:* This option is ignored if C(image: ignore) or C(*: ignore) is specified in the
+      - "B(Warning:) This option is ignored if C(image: ignore) or C(*: ignore) is specified in the
         I(comparisons) option."
     type: bool
     default: no
@@ -451,7 +451,7 @@ options:
       - log_opt
   mac_address:
     description:
-      - Container MAC address (e.g. 92:d0:c6:0a:29:33).
+      - Container MAC address (for example, C(92:d0:c6:0a:29:33)).
     type: str
   memory:
     description:
@@ -495,7 +495,8 @@ options:
         required: true
       source:
         description:
-          - Mount source (e.g. a volume name or a host path).
+          - Mount source.
+          - For example, this can be a volume name or a host path.
           - If not supplied when I(type=volume) an anonymous volume will be created.
         type: str
       type:
@@ -619,7 +620,7 @@ options:
   networks_cli_compatible:
     description:
       - "If I(networks_cli_compatible) is set to C(yes) (default), this module will behave as
-         C(docker run --network) and will *not* add the default network if I(networks) is
+         C(docker run --network) and will B(not) add the default network if I(networks) is
          specified. If I(networks) is not specified, the default network will be attached."
       - "When I(networks_cli_compatible) is set to C(no) and networks are provided to the module
          via the I(networks) option, the module behaves differently than C(docker run --network):
@@ -681,7 +682,7 @@ options:
         Since community.general 0.2.0, if the source port range has length 1, the port will not be assigned
         to the first port of the destination range, but to a free port in that range. This is the
         same behavior as for C(docker) command line utility.
-      - "Bind addresses must be either IPv4 or IPv6 addresses. Hostnames are *not* allowed. This
+      - "Bind addresses must be either IPv4 or IPv6 addresses. Hostnames are B(not) allowed. This
         is different from the C(docker) command line utility. Use the R(dig lookup,ansible_collections.community.general.dig_lookup)
         to resolve hostnames."
       - A value of C(all) will publish all exposed container ports to random host ports, ignoring
@@ -701,7 +702,7 @@ options:
     description:
        - If true, always pull the latest version of an image. Otherwise, will only pull an image
          when missing.
-       - "*Note:* images are only pulled when specified by name. If the image is specified
+       - "B(Note:) images are only pulled when specified by name. If the image is specified
          as a image ID (hash), it cannot be pulled."
     type: bool
     default: no

plugins/modules/docker_image.py

@@ -28,7 +28,7 @@ options:
          be specified when this value is used."
       - "Use C(pull) to pull the image from a registry."
       - "Use C(local) to make sure that the image is already available on the local
-         docker daemon, i.e. do not try to build, pull or load the image."
+         docker daemon. This means that the module does not try to build, pull or load the image."
     type: str
     choices:
     - build
@@ -101,7 +101,8 @@ options:
             type: int
           memswap:
             description:
-              - Total memory (memory + swap), -1 to disable swap.
+              - Total memory (memory + swap).
+              - Use C(-1) to disable swap.
             type: int
           cpushares:
             description:
@@ -109,7 +110,8 @@ options:
             type: int
           cpusetcpus:
             description:
-              - CPUs in which to allow execution, e.g., "0-3", "0,1".
+              - CPUs in which to allow execution.
+              - For example, C(0-3) or C(0,1).
             type: str
       use_config_proxy:
         description:

plugins/modules/docker_login.py

@@ -15,7 +15,7 @@ DOCUMENTATION = '''
 module: docker_login
 short_description: Log into a Docker registry.
 description:
-    - Provides functionality similar to the "docker login" command.
+    - Provides functionality similar to the C(docker login) command.
     - Authenticate with a docker registry and add the credentials to your local Docker config file respectively the
       credentials store associated to the registry. Adding the credentials to the config files resp. the credential
       store allows future connections to the registry using tools such as Ansible's Docker modules, the Docker CLI

plugins/modules/docker_network.py

@@ -12,7 +12,7 @@ module: docker_network
 short_description: Manage Docker networks
 description:
   - Create/remove Docker networks and connect containers to them.
-  - Performs largely the same function as the "docker network" CLI subcommand.
+  - Performs largely the same function as the C(docker network) CLI subcommand.
 options:
   name:
     description:
@@ -155,7 +155,7 @@ notes:
     It does not try to reconnect containers, except the ones listed in (I(connected), and even for these, it does not consider specific
     connection options like fixed IP addresses or MAC addresses. If you need more control over how the containers are connected to the
     network, loop the M(community.docker.docker_container) module to loop over your containers to make sure they are connected properly.
-  - The module does not support Docker Swarm, i.e. it will not try to disconnect or reconnect services. If services are connected to the
+  - The module does not support Docker Swarm. This means that it will not try to disconnect or reconnect services. If services are connected to the
     network, deleting the network will fail. When network options are changed, the network has to be deleted and recreated, so this will
     fail as well.
 

plugins/modules/docker_node_info.py

@@ -31,7 +31,7 @@ options:
     elements: str
   self:
     description:
-      - If C(true), queries the node (i.e. the docker daemon) the module communicates with.
+      - If C(true), queries the node (that is, the docker daemon) the module communicates with.
       - If C(true) then I(name) is ignored.
       - If C(false) then query depends on I(name) presence and value.
     type: bool

plugins/modules/docker_secret.py

@@ -16,8 +16,8 @@ short_description: Manage docker secrets.
 
 description:
      - Create and remove Docker secrets in a Swarm environment. Similar to C(docker secret create) and C(docker secret rm).
-     - Adds to the metadata of new secrets 'ansible_key', an encrypted hash representation of the data, which is then used
+     - Adds to the metadata of new secrets C(ansible_key), an encrypted hash representation of the data, which is then used
-       in future runs to test if a secret has changed. If 'ansible_key is not present, then a secret will not be updated
+       in future runs to test if a secret has changed. If C(ansible_key) is not present, then a secret will not be updated
        unless the I(force) option is set.
      - Updates to secrets are performed by removing the secret and creating it again.
 options:

plugins/modules/docker_stack.py

@@ -14,7 +14,7 @@ module: docker_stack
 author: "Dario Zanzico (@dariko)"
 short_description: docker stack module
 description:
-  - Manage docker stacks using the 'docker stack' command
+  - Manage docker stacks using the C(docker stack) command
     on the target node (see examples).
 options:
   name:

plugins/modules/docker_swarm_service.py

@@ -103,7 +103,7 @@ options:
       - List or dictionary of the service environment variables.
       - If passed a list each items need to be in the format of C(KEY=VALUE).
       - If passed a dictionary values which might be parsed as numbers,
-        booleans or other types by the YAML parser must be quoted (e.g. C("true"))
+        booleans or other types by the YAML parser must be quoted (for example C("true"))
         in order to avoid data loss.
       - Corresponds to the C(--env) option of C(docker service create).
     type: raw
@@ -242,7 +242,7 @@ options:
     suboptions:
       source:
         description:
-          - Mount source (e.g. a volume name or a host path).
+          - Mount source (for example a volume name or a host path).
           - Must be specified if I(type) is not C(tmpfs).
         type: str
       target:

plugins/modules/docker_volume.py

@@ -13,7 +13,7 @@ module: docker_volume
 short_description: Manage Docker volumes
 description:
   - Create/remove Docker volumes.
-  - Performs largely the same function as the "docker volume" CLI subcommand.
+  - Performs largely the same function as the C(docker volume) CLI subcommand.
 options:
   volume_name:
     description:
@@ -32,7 +32,7 @@ options:
   driver_options:
     description:
       - "Dictionary of volume settings. Consult docker docs for valid options and values:
-        U(https://docs.docker.com/engine/reference/commandline/volume_create/#driver-specific-options)"
+        U(https://docs.docker.com/engine/reference/commandline/volume_create/#driver-specific-options)."
     type: dict
 
   labels:
@@ -43,8 +43,8 @@ options:
   recreate:
     description:
       - Controls when a volume will be recreated when I(state) is C(present). Please
-        note that recreating an existing volume will cause **any data in the existing volume
+        note that recreating an existing volume will cause B(any data in the existing volume
-        to be lost!** The volume will be deleted and a new volume with the same name will be
+        to be lost!) The volume will be deleted and a new volume with the same name will be
         created.
       - The value C(always) forces the volume to be always recreated.
       - The value C(never) makes sure the volume will not be recreated.

plugins/modules/docker_volume_info.py

@@ -12,7 +12,7 @@ DOCUMENTATION = '''
 module: docker_volume_info
 short_description: Retrieve facts about Docker volumes
 description:
-  - Performs largely the same function as the "docker volume inspect" CLI subcommand.
+  - Performs largely the same function as the C(docker volume inspect) CLI subcommand.
 options:
   name:
     description: