ansible-doc man formatter: fail with better error message when description isn't there (#70046) (#70485)

* ansible-doc man formatter: do not crash when description isn't there.
* Change to report a better error message when description is not there.
* Add test.

(cherry picked from commit 9164b96774)

changelogs/fragments/70046-ansible-doc-description-crash.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- "ansible-doc - improve error message in text formatter when ``description`` is missing for a (sub-)option or a return value or its ``contains`` (https://github.com/ansible/ansible/pull/70046)."

lib/ansible/cli/doc.py

@@ -526,6 +526,8 @@ class DocCLI(CLI):
 
             text.append("%s%s %s" % (base_indent, opt_leadin, o))
 
+            if 'description' not in opt:
+                raise AnsibleError("All (sub-)options and return values must have a 'description' field")
             if isinstance(opt['description'], list):
                 for entry_idx, entry in enumerate(opt['description'], 1):
                     if not isinstance(entry, string_types):

test/integration/targets/ansible-doc/library/test_docs_missing_description.py

@@ -0,0 +1,40 @@
+#!/usr/bin/python
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: test_docs_returns
+short_description: Test module
+description:
+    - Test module
+author:
+    - Ansible Core Team
+options:
+    test:
+        type: str
+'''
+
+EXAMPLES = '''
+'''
+
+RETURN = '''
+'''
+
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    module = AnsibleModule(
+        argument_spec=dict(
+            test=dict(type='str'),
+        ),
+    )
+
+    module.exit_json()
+
+
+if __name__ == '__main__':
+    main()

test/integration/targets/ansible-doc/test.yml

@@ -3,6 +3,18 @@
   environment:
     ANSIBLE_LIBRARY: "{{ playbook_dir }}/library"
   tasks:
+    - name: module with missing description return docs
+      command: ansible-doc test_docs_missing_description
+      register: result
+      ignore_errors: true
+
+    - assert:
+        that:
+          - result is failed
+          - |
+            "ERROR! Unable to retrieve documentation from 'test_docs_missing_description' due to: All (sub-)options and return values must have a 'description' field"
+            in result.stderr
+
     - name: module with suboptions
       command: ansible-doc test_docs_suboptions
       register: result