ansible-doc: print where the description is missing (#85320)

* ansible-doc: print where the description is missing

Signed-off-by: Thomas Sjögren <konstruktoid@users.noreply.github.com>
Co-authored-by: Sloane Hertel <19572925+s-hertel@users.noreply.github.com>

changelogs/fragments/ansible-doc-description-verbosity.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - ansible-doc - Return a more verbose error message when the ``description`` field is missing.

lib/ansible/cli/doc.py

@@ -1265,7 +1265,7 @@ class DocCLI(CLI, RoleMixin):
 
             # description is specifically formatted and can either be string or list of strings
             if 'description' not in opt:
-                raise AnsibleError("All (sub-)options and return values must have a 'description' field")
+                raise AnsibleError("All (sub-)options and return values must have a 'description' field", obj=o)
             text.append('')
 
             # TODO: push this to top of for and sort by size, create indent on largest key?

test/integration/targets/ansible-doc/roles/test_role4/meta/argument_specs.yml

@@ -0,0 +1,34 @@
+---
+argument_specs:
+    main:
+        short_description: test_role4 from roles subdir
+        description:
+            - In to am attended desirous raptures B(declared) diverted confined at. Collected instantly remaining
+              up certainly to C(necessary) as. Over walk dull into son boy door went new.
+            - At or happiness commanded daughters as. Is I(handsome) an declared at received in extended vicinity
+              subjects. Into miss on he over been late pain an. Only week bore boy what fat case left use. Match round
+              scale now style far times. Your me past an much.
+        author:
+          - John Doe (@john)
+          - Jane Doe (@jane)
+        attributes:
+          diff_mode:
+            description: Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode
+            support: partial
+            details: Not all modules used support this
+        options:
+            myopt1:
+                description:
+                    - First option.
+                type: "str"
+                required: true
+
+            myopt2:
+                type: "int"
+                default: 8000
+
+            myopt3:
+                description:
+                    - Third option.
+                type: "bool"
+                default: false

test/integration/targets/ansible-doc/roles/test_role4/meta/main.yml

@@ -0,0 +1,10 @@
+# This meta/main.yml exists to test that it is NOT read, with preference being
+# given to the meta/argument_specs.yml file. This spec contains an additional
+# entry point that the argument_specs.yml does not. If this file # were read,
+# the additional entrypoints would show up in --list output, breaking # tests.
+---
+argument_specs:
+    main:
+        short_description: test_role4 from roles subdir
+    holden:
+        short_description: Rocinante pilot

test/integration/targets/ansible-doc/runme.sh

@@ -138,7 +138,7 @@ test "$output" -eq 4
 echo "testing standalone roles"
 # Include normal roles (no collection filter)
 output=$(ansible-doc -t role -l --playbook-dir . | wc -l)
-test "$output" -eq 8
+test "$output" -eq 11
 
 echo "testing role precedence"
 # Test that a role in the playbook dir with the same name as a role in the
@@ -288,5 +288,8 @@ echo "test 'sidecar' for no extension module  with .py doc"
 echo "test 'sidecar' for no extension module  with .yml doc"
 [ "$(ansible-doc -M ./library -l ansible.legacy |grep -v 'UNDOCUMENTED' |grep -c facts_one)" == "1" ]
 
-echo "Test j2 plugins get jinja2 instead of path"
+echo "test j2 plugins get jinja2 instead of path"
 ansible-doc -t filter map 2>&1 |grep "${GREP_OPTS[@]}" '(Jinja2)'
+
+echo "test missing description in test_role4 argument spec"
+ansible-doc -t role -r ./roles test_role4 2>&1 >/dev/null | grep -q 'Error extracting role docs from '\''test_role4'\'': All (sub-)options and return values must have a '\''description'\'' field'