Improve examples: use FQCNs and always add name: to tasks (#624) (#627)

* Improve examples: use FQCNs and always add name: to tasks.

* Improvements.

Co-authored-by: Don Naro <dnaro@redhat.com>

---------

Co-authored-by: Don Naro <dnaro@redhat.com>
(cherry picked from commit 7bdb2127e0)

Co-authored-by: Felix Fontein <felix@fontein.de>

plugins/modules/docker_compose.py

@@ -201,7 +201,8 @@ EXAMPLES = '''
         project_src: flask
       register: output
 
-    - ansible.builtin.debug:
+    - name: Show results
+      ansible.builtin.debug:
         var: output
 
     - name: Run `docker-compose up` again
@@ -210,7 +211,8 @@ EXAMPLES = '''
         build: false
       register: output
 
-    - ansible.builtin.debug:
+    - name: Show results
+      ansible.builtin.debug:
         var: output
 
     - ansible.builtin.assert:
@@ -223,10 +225,12 @@ EXAMPLES = '''
         stopped: true
       register: output
 
-    - ansible.builtin.debug:
+    - name: Show results
+      ansible.builtin.debug:
         var: output
 
-    - ansible.builtin.assert:
+    - name: Verify that web and db services are running
+      ansible.builtin.assert:
         that:
           - "not output.services.web.flask_web_1.state.running"
           - "not output.services.db.flask_db_1.state.running"
@@ -238,10 +242,12 @@ EXAMPLES = '''
         restarted: true
       register: output
 
-    - ansible.builtin.debug:
+    - name: Show results
+      ansible.builtin.debug:
         var: output
 
-    - ansible.builtin.assert:
+    - name: Verify that web and db services are running
+      ansible.builtin.assert:
         that:
           - "output.services.web.flask_web_1.state.running"
           - "output.services.db.flask_db_1.state.running"
@@ -250,13 +256,15 @@ EXAMPLES = '''
   hosts: localhost
   gather_facts: false
   tasks:
-    - community.docker.docker_compose:
+    - name: Scale the web service to two instances
+      community.docker.docker_compose:
         project_src: flask
         scale:
           web: 2
       register: output
 
-    - ansible.builtin.debug:
+    - name: Show results
+      ansible.builtin.debug:
         var: output
 
 - name: Run with inline Compose file version 2
@@ -264,11 +272,13 @@ EXAMPLES = '''
   hosts: localhost
   gather_facts: false
   tasks:
-    - community.docker.docker_compose:
+    - name: Remove flask project
+      community.docker.docker_compose:
         project_src: flask
         state: absent
 
-    - community.docker.docker_compose:
+    - name: Start flask project with inline definition
+      community.docker.docker_compose:
         project_name: flask
         definition:
           version: '2'
@@ -286,10 +296,12 @@ EXAMPLES = '''
                 - db
       register: output
 
-    - ansible.builtin.debug:
+    - name: Show results
+      ansible.builtin.debug:
         var: output
 
-    - ansible.builtin.assert:
+    - name: Verify that the db and web services are running
+      ansible.builtin.assert:
         that:
           - "output.services.web.flask_web_1.state.running"
           - "output.services.db.flask_db_1.state.running"
@@ -299,11 +311,13 @@ EXAMPLES = '''
   hosts: localhost
   gather_facts: false
   tasks:
-    - community.docker.docker_compose:
+    - name: Remove flask project
+      community.docker.docker_compose:
         project_src: flask
         state: absent
 
-    - community.docker.docker_compose:
+    - name: Start flask project with inline definition
+      community.docker.docker_compose:
         project_name: flask
         definition:
             db:
@@ -319,10 +333,12 @@ EXAMPLES = '''
                 - db
       register: output
 
-    - ansible.builtin.debug:
+    - name: Show results
+      ansible.builtin.debug:
         var: output
 
-    - ansible.builtin.assert:
+    - name: Verify that web and db services are running
+      ansible.builtin.assert:
         that:
           - "output.services.web.flask_web_1.state.running"
           - "output.services.db.flask_db_1.state.running"

plugins/modules/docker_container_exec.py

@@ -103,7 +103,7 @@ EXAMPLES = '''
   register: result
 
 - name: Print stdout
-  debug:
+  ansible.builtin.debug:
     var: result.stdout
 
 - name: Run a simple command (argv)
@@ -117,7 +117,7 @@ EXAMPLES = '''
   register: result
 
 - name: Print stderr lines
-  debug:
+  ansible.builtin.debug:
     var: result.stderr_lines
 '''
 

plugins/modules/docker_host_info.py

@@ -143,7 +143,8 @@ EXAMPLES = '''
         - key2=value2
   register: result
 
-- ansible.builtin.debug:
+- name: Show host information
+  ansible.builtin.debug:
     var: result.host_info
 
 '''

plugins/modules/docker_swarm_info.py

@@ -100,8 +100,6 @@ EXAMPLES = '''
       Docker in Swarm mode: {{ result.docker_swarm_active }}
       This is a Manager node: {{ result.docker_swarm_manager }}
 
-- block:
-
 - name: Get info on Docker Swarm and list of registered nodes
   community.docker.docker_swarm_info:
     nodes: true
@@ -120,7 +118,8 @@ EXAMPLES = '''
       name: mynode
   register: result
 
-- ansible.builtin.debug:
+- name: Show swarm facts
+  ansible.builtin.debug:
     var: result.swarm_facts
 
 - name: Get the swarm unlock key
@@ -128,7 +127,8 @@ EXAMPLES = '''
     unlock_key: true
   register: result
 
-- ansible.builtin.debug:
+- name: Print swarm unlock key
+  ansible.builtin.debug:
     var: result.swarm_unlock_key
 
 '''