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

* 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>

plugins/modules/docker_compose.py

@@ -208,7 +208,8 @@ EXAMPLES = '''
         project_src: flask
       register: output
 
-    - ansible.builtin.debug:
+    - name: Show results
+      ansible.builtin.debug:
         var: output
 
     - name: Run `docker-compose up` again
@@ -217,7 +218,8 @@ EXAMPLES = '''
         build: false
       register: output
 
-    - ansible.builtin.debug:
+    - name: Show results
+      ansible.builtin.debug:
         var: output
 
     - ansible.builtin.assert:
@@ -230,10 +232,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"
@@ -245,10 +249,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"
@@ -257,13 +263,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
@@ -271,11 +279,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'
@@ -293,10 +303,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"
@@ -306,11 +318,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:
@@ -326,10 +340,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

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

plugins/modules/docker_host_info.py

@@ -160,7 +160,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

@@ -103,8 +103,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
@@ -123,7 +121,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
@@ -131,7 +130,8 @@ EXAMPLES = '''
     unlock_key: true
   register: result
 
-- ansible.builtin.debug:
+- name: Print swarm unlock key
+  ansible.builtin.debug:
     var: result.swarm_unlock_key
 
 '''