better error message for malformed documentation (#84705)

No the file name that caused the error will be apparent
---------

Signed-off-by: Abhijeet Kasurde <Akasurde@redhat.com>
Co-authored-by: Abhijeet Kasurde <Akasurde@redhat.com>

changelogs/fragments/84705-error-message-malformed-plugin-documentation.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - improved error message for yaml parsing errors in plugin documentation

lib/ansible/plugins/loader.py

@@ -16,6 +16,7 @@ import warnings
 from collections import defaultdict, namedtuple
 from importlib import import_module
 from traceback import format_exc
+from yaml.parser import ParserError
 
 import ansible.module_utils.compat.typing as t
 
@@ -407,7 +408,10 @@ class PluginLoader:
 
             # if type name != 'module_doc_fragment':
             if type_name in C.CONFIGURABLE_PLUGINS and not C.config.has_configuration_definition(type_name, name):
-                dstring = AnsibleLoader(getattr(module, 'DOCUMENTATION', ''), file_name=path).get_single_data()
+                try:
+                    dstring = AnsibleLoader(getattr(module, 'DOCUMENTATION', ''), file_name=path).get_single_data()
+                except ParserError as e:
+                    raise AnsibleError(f"plugin {name} has malformed documentation!") from e
 
                 # TODO: allow configurable plugins to use sidecar
                 # if not dstring:

test/integration/targets/ansible-doc/lookup_plugins/broken_docs.py

@@ -0,0 +1,16 @@
+# Copyright (c) 2022 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import annotations
+
+
+DOCUMENTATION = """
+    name: broken_docs
+    -
+"""
+
+EXAMPLE = """
+"""
+
+RETURN = """
+"""

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

@@ -181,3 +181,13 @@
           - '"[DEPRECATION WARNING]" in result.stderr'
           - '"deprecated_with_adj_docs " in result.stdout'
           - '"AUTHOR: Ansible Core Team" in result.stdout'
+
+    - name: Handle plugin docs
+      debug:
+        msg: "{{ lookup('broken_docs') }}"
+      register: r
+      ignore_errors: yes
+
+    - assert:
+        that:
+          - "'plugin broken_docs has malformed documentation' in r.msg"