Deprecate returned facts. (#52518)

docs/docsite/rst/porting_guides/porting_guide_2.8.rst

@@ -195,7 +195,17 @@ Noteworthy module changes
 * The ``digital_ocean`` module has been deprecated in favor of modules that do not require external dependencies.
   This allows for more flexibility and better module support.
 
+* The ``docker_container`` module has deprecated the returned fact ``docker_container``. The same value is
+  available as the returned variable ``docker_container``. The returned fact will be removed in Ansible 2.12.
+* The ``docker_network`` module has deprecated the returned fact ``docker_container``. The same value is
+  available as the returned variable ``docker_network``. The returned fact will be removed in Ansible 2.12.
+* The ``docker_volume`` module has deprecated the returned fact ``docker_container``. The same value is
+  available as the returned variable ``docker_volume``. The returned fact will be removed in Ansible 2.12.
+
 * The ``docker_service`` module was renamed to :ref:`docker_compose <docker_compose_module>`.
+* The renamed ``docker_compose`` module used to return one fact per service, named same as the service. A dictionary
+  of these facts is returned as the regular return value ``service_facts``. The returned facts will be removed in
+  Ansible 2.12.
 
 * The ``docker_swarm_service`` module no longer sets a defaults for the following options:
     * ``user``. Before, the default was ``root``.

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

@@ -307,7 +307,7 @@ service_facts:
   - A dictionary mapping the service's name to a dictionary of containers.
   - Note that facts are part of the registered vars since Ansible 2.8. For compatibility reasons, the facts
     are also accessible directly. The service's name is the variable with which the container dictionary
-    can be accessed.
+    can be accessed. Note that the returned facts will be removed in Ansible 2.12.
   returned: success
   type: complex
   contains:

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

@@ -878,7 +878,7 @@ docker_container:
       - Before 2.3 this was 'ansible_docker_container' but was renamed due to conflicts with the connection plugin.
       - Facts representing the current state of the container. Matches the docker inspection output.
       - Note that facts are part of the registered vars since Ansible 2.8. For compatibility reasons, the facts
-        are also accessible directly.
+        are also accessible directly. Note that the returned fact will be removed in Ansible 2.12.
       - Empty if C(state) is I(absent)
       - If detached is I(False), will include Output attribute containing any output from container run.
     returned: always

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

@@ -245,7 +245,7 @@ docker_network:
     description:
     - Network inspection results for the affected network.
     - Note that facts are part of the registered vars since Ansible 2.8. For compatibility reasons, the facts
-      are also accessible directly.
+      are also accessible directly. Note that the returned fact will be removed in Ansible 2.12.
     returned: success
     type: dict
     sample: {}

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

@@ -119,7 +119,7 @@ docker_volume:
     description:
     - Volume inspection results for the affected volume.
     - Note that facts are part of the registered vars since Ansible 2.8. For compatibility reasons, the facts
-      are also accessible directly.
+      are also accessible directly. Note that the returned fact will be removed in Ansible 2.12.
     returned: success
     type: dict
     sample: {}