Documentation: fix modules doc formatting

lib/ansible/modules/file.py

@@ -111,36 +111,38 @@
 - module: ansible.builtin.stat
 - module: ansible.builtin.template
 - module: ansible.windows.win_file
+notes:
+- Supports C(check_mode).
 author:
 - Ansible Core Team
 - Michael DeHaan
 '''
 
 EXAMPLES = r'''
 - name: Change file ownership, group and permissions
-  file:
+  ansible.builtin.file:
     path: /etc/foo.conf
     owner: foo
     group: foo
     mode: '0644'
 
 - name: Give insecure permissions to an existing file
-  file:
+  ansible.builtin.file:
     path: /work
     owner: root
     group: root
     mode: '1777'
 
 - name: Create a symbolic link
-  file:
+  ansible.builtin.file:
     src: /file/to/link/to
     dest: /path/to/symlink
     owner: foo
     group: foo
     state: link
 
 - name: Create two hard links
-  file:
+  ansible.builtin.file:
     src: '/tmp/{{ item.src }}'
     dest: '{{ item.dest }}'
     state: hard
@@ -149,71 +151,71 @@
     - { src: z, dest: k }
 
 - name: Touch a file, using symbolic modes to set the permissions (equivalent to 0644)
-  file:
+  ansible.builtin.file:
     path: /etc/foo.conf
     state: touch
     mode: u=rw,g=r,o=r
 
 - name: Touch the same file, but add/remove some permissions
-  file:
+  ansible.builtin.file:
     path: /etc/foo.conf
     state: touch
     mode: u+rw,g-wx,o-rwx
 
-- name: Touch again the same file, but dont change times this makes the task idempotent
-  file:
+- name: Touch again the same file, but do not change times this makes the task idempotent
+  ansible.builtin.file:
     path: /etc/foo.conf
     state: touch
     mode: u+rw,g-wx,o-rwx
     modification_time: preserve
     access_time: preserve
 
 - name: Create a directory if it does not exist
-  file:
+  ansible.builtin.file:
     path: /etc/some_directory
     state: directory
     mode: '0755'
 
 - name: Update modification and access time of given file
-  file:
+  ansible.builtin.file:
     path: /etc/some_file
     state: file
     modification_time: now
     access_time: now
 
 - name: Set access time based on seconds from epoch value
-  file:
+  ansible.builtin.file:
     path: /etc/another_file
     state: file
     access_time: '{{ "%Y%m%d%H%M.%S" | strftime(stat_var.stat.atime) }}'
 
 - name: Recursively change ownership of a directory
-  file:
+  ansible.builtin.file:
     path: /etc/foo
     state: directory
     recurse: yes
     owner: foo
     group: foo
 
 - name: Remove file (delete file)
-  file:
+  ansible.builtin.file:
     path: /etc/foo.txt
     state: absent
 
 - name: Recursively remove directory
-  file:
+  ansible.builtin.file:
     path: /etc/foo
     state: absent
 
 '''
 RETURN = r'''
 dest:
-    description: Destination file/path, equal to the value passed to I(path)
+    description: Destination file/path, equal to the value passed to I(path).
     returned: state=touch, state=hard, state=link
     type: str
     sample: /path/to/file.txt
 path:
-    description: Destination file/path, equal to the value passed to I(path)
+    description: Destination file/path, equal to the value passed to I(path).
     returned: state=absent, state=directory, state=file
     type: str
     sample: /path/to/file.txt

lib/ansible/modules/rpm_key.py

@@ -44,29 +44,34 @@
         - This will be used to verify the specified key.
       type: str
       version_added: 2.9
+notes:
+  - Supports C(check_mode).
 '''
 
 EXAMPLES = '''
 - name: Import a key from a url
-  rpm_key:
+  ansible.builtin.rpm_key:
     state: present
     key: http://apt.sw.be/RPM-GPG-KEY.dag.txt
 
 - name: Import a key from a file
-  rpm_key:
+  ansible.builtin.rpm_key:
     state: present
     key: /path/to/key.gpg
 
 - name: Ensure a key is not present in the db
-  rpm_key:
+  ansible.builtin.rpm_key:
     state: absent
     key: DEADB33F
 
 - name: Verify the key, using a fingerprint, before import
-  rpm_key:
+  ansible.builtin.rpm_key:
     key: /path/to/RPM-GPG-KEY.dag.txt
     fingerprint: EBC6 E12C 62B1 C734 026B  2122 A20E 5214 6B8D 79E6
 '''
+
+RETURN = r'''#'''
+
 import re
 import os.path
 import tempfile

lib/ansible/modules/service_facts.py

@@ -14,7 +14,7 @@
 module: service_facts
 short_description: Return service state information as fact data
 description:
-     - Return service state information as fact data for various service management utilities
+     - Return service state information as fact data for various service management utilities.
 version_added: "2.5"
 requirements: ["Any of the following supported init systems: systemd, sysv, upstart, AIX SRC"]
 
@@ -26,18 +26,19 @@
     using the string value of the service name as the key in order to obtain
     the fact data value like C(ansible_facts.services['zuul-gateway'])
   - AIX SRC was added in version 2.11.
+  - Supports C(check_mode).
 
 author:
   - Adam Miller (@maxamillion)
 '''
 
 EXAMPLES = r'''
 - name: Populate service facts
-  service_facts:
+  ansible.builtin.service_facts:
 
-- debug:
+- name: Print service facts
+  ansible.builtin.debug:
     var: ansible_facts.services
-
 '''
 
 RETURN = r'''

lib/ansible/modules/stat.py

@@ -64,17 +64,20 @@
 seealso:
 - module: ansible.builtin.file
 - module: ansible.windows.win_stat
+notes:
+- Supports C(check_mode).
 author: Bruce Pennypacker (@bpennypacker)
 '''
 
 EXAMPLES = r'''
 # Obtain the stats of /etc/foo.conf, and check that the file still belongs
 # to 'root'. Fail otherwise.
 - name: Get stats of a file
-  stat:
+  ansible.builtin.stat:
     path: /etc/foo.conf
   register: st
-- fail:
+- name: Fail if the file does not belong to 'root'
+  ansible.builtin.fail:
     msg: "Whoops! file ownership has changed"
   when: st.stat.pw_name != 'root'
 
@@ -84,51 +87,56 @@
 # Run this to understand the structure, the skipped ones do not pass the
 # check performed by 'when'
 - name: Get stats of the FS object
-  stat:
+  ansible.builtin.stat:
     path: /path/to/something
   register: sym
 
-- debug:
+- name: Print a debug message
+  ansible.builtin.debug:
     msg: "islnk isn't defined (path doesn't exist)"
   when: sym.stat.islnk is not defined
 
-- debug:
+- name: Print a debug message
+  ansible.builtin.debug:
     msg: "islnk is defined (path must exist)"
   when: sym.stat.islnk is defined
 
-- debug:
+- name: Print a debug message
+  ansible.builtin.debug:
     msg: "Path exists and is a symlink"
   when: sym.stat.islnk is defined and sym.stat.islnk
 
-- debug:
+- name: Print a debug message
+  ansible.builtin.debug:
     msg: "Path exists and isn't a symlink"
   when: sym.stat.islnk is defined and sym.stat.islnk == False
 
 
 # Determine if a path exists and is a directory.  Note that we need to test
 # both that p.stat.isdir actually exists, and also that it's set to true.
 - name: Get stats of the FS object
-  stat:
+  ansible.builtin.stat:
     path: /path/to/something
   register: p
-- debug:
+- name: Print a debug message
+  ansible.builtin.debug:
     msg: "Path exists and is a directory"
   when: p.stat.isdir is defined and p.stat.isdir
 
-- name: Don't do checksum
-  stat:
+- name: Don not do checksum
+  ansible.builtin.stat:
     path: /path/to/myhugefile
     get_checksum: no
 
 - name: Use sha256 to calculate checksum
-  stat:
+  ansible.builtin.stat:
     path: /path/to/something
     checksum_algorithm: sha256
 '''
 
 RETURN = r'''
 stat:
-    description: dictionary containing all the stat data, some platforms might add additional fields
+    description: Dictionary containing all the stat data, some platforms might add additional fields.
     returned: success
     type: complex
     contains:

lib/ansible/modules/subversion.py

@@ -18,8 +18,8 @@
 author:
 - Dane Summers (@dsummersl) <njharman@gmail.com>
 notes:
-   - Requires I(svn) to be installed on the client.
    - This module does not handle externals.
+   - Supports C(check_mode).
 options:
   repo:
     description:
@@ -47,7 +47,7 @@
   in_place:
     description:
       - If the directory exists, then the working copy will be checked-out over-the-top using
-        svn checkout --force; if force is specified then existing files with different content are reverted
+        svn checkout --force; if force is specified then existing files with different content are reverted.
     type: bool
     default: "no"
     version_added: "2.6"
@@ -105,24 +105,26 @@
 
 EXAMPLES = '''
 - name: Checkout subversion repository to specified folder
-  subversion:
+  ansible.builtin.subversion:
     repo: svn+ssh://an.example.org/path/to/repo
     dest: /src/checkout
 
 - name: Export subversion directory to folder
-  subversion:
+  ansible.builtin.subversion:
     repo: svn+ssh://an.example.org/path/to/repo
     dest: /src/export
     export: yes
 
 - name: Get information about the repository whether or not it has already been cloned locally
-- subversion:
+  ansible.builtin.subversion:
     repo: svn+ssh://an.example.org/path/to/repo
     dest: /src/checkout
     checkout: no
     update: no
 '''
 
+RETURN = r'''#'''
+
 import os
 import re