filter: add documentation for msg parameter (#81110)

* mandatory filter provides `msg` parameter. Document the same.

Fixes: #81105

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

lib/ansible/plugins/filter/core.py

@@ -327,8 +327,7 @@ def mandatory(a, msg=None):
 
         if msg is not None:
             raise AnsibleFilterError(to_native(msg))
-        else:
-            raise AnsibleFilterError("Mandatory variable %s not defined." % name)
+        raise AnsibleFilterError("Mandatory variable %s not defined." % name)
 
     return a
 

lib/ansible/plugins/filter/mandatory.yml

@@ -10,11 +10,18 @@ DOCUMENTATION:
       description: Mandatory expression.
       type: raw
       required: true
+    msg:
+      description: The customized message that is printed when the given variable is not defined.
+      type: str
+      required: false
 EXAMPLES: |
 
     # results in a Filter Error
     {{ notdefined | mandatory }}
 
+    # print a custom error message
+    {{ notdefined | mandatory(msg='This variable is required.') }}
+
 RETURN:
   _value:
     description: The input if defined, otherwise an error.