From 8edba0bb72aa81464dfd55ac4fed6ca9f9f81972 Mon Sep 17 00:00:00 2001
From: Abhijeet Kasurde <akasurde@redhat.com>
Date: Wed, 12 Jul 2023 16:02:56 -0700
Subject: [PATCH] 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       | 3 +--
 lib/ansible/plugins/filter/mandatory.yml | 7 +++++++
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/lib/ansible/plugins/filter/core.py b/lib/ansible/plugins/filter/core.py
index 98a2a03142d..43c310c43b0 100644
--- a/lib/ansible/plugins/filter/core.py
+++ b/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
 
diff --git a/lib/ansible/plugins/filter/mandatory.yml b/lib/ansible/plugins/filter/mandatory.yml
index 5addf15986a..14058845a74 100644
--- a/lib/ansible/plugins/filter/mandatory.yml
+++ b/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.