From 9164b9677434042cd64a45a0dac1289ec40d819d Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Mon, 6 Jul 2020 19:29:03 +0200
Subject: [PATCH] ansible-doc man formatter: fail with better error message
 when description isn't there (#70046)

* 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.
---
 .../70046-ansible-doc-description-crash.yml   |  2 +
 lib/ansible/cli/doc.py                        |  2 +
 .../library/test_docs_missing_description.py  | 40 +++++++++++++++++++
 test/integration/targets/ansible-doc/test.yml | 12 ++++++
 4 files changed, 56 insertions(+)
 create mode 100644 changelogs/fragments/70046-ansible-doc-description-crash.yml
 create mode 100644 test/integration/targets/ansible-doc/library/test_docs_missing_description.py

diff --git a/changelogs/fragments/70046-ansible-doc-description-crash.yml b/changelogs/fragments/70046-ansible-doc-description-crash.yml
new file mode 100644
index 00000000000..2220fb981ab
--- /dev/null
+++ b/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)."
diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py
index 0572ec9d59c..cfb38f82fdf 100644
--- a/lib/ansible/cli/doc.py
+++ b/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):
diff --git a/test/integration/targets/ansible-doc/library/test_docs_missing_description.py b/test/integration/targets/ansible-doc/library/test_docs_missing_description.py
new file mode 100644
index 00000000000..6ed41836b0b
--- /dev/null
+++ b/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()
diff --git a/test/integration/targets/ansible-doc/test.yml b/test/integration/targets/ansible-doc/test.yml
index e03fb49a48e..a077a9941ac 100644
--- a/test/integration/targets/ansible-doc/test.yml
+++ b/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