document return values of file module (#69560)

* document return values of file module
* Clarify whether path or dest input is used as dest output in file module

Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>

1 files changed, 11 insertions, 2 deletions

diff --git a/lib/ansible/modules/file.py b/lib/ansible/modules/file.py
index ba5d4bd7fa..d8178645e4 100644
--- a/lib/ansible/modules/file.py
+++ b/lib/ansible/modules/file.py
@@ -206,7 +206,16 @@ EXAMPLES = r'''
 
 '''
 RETURN = r'''
-
+dest:
+    description: Destination file/path, equal to the value passed to I(path)
+    returned: state=touch, state=hard, state=link
+    type: str
+    sample: /path/to/file.txt
+path:
+    description: Destination file/path, equal to the value passed to I(path)
+    returned: state=absent, state=directory, state=file
+    type: str
+    sample: /path/to/file.txt
 '''
 
 import errno
@@ -608,7 +617,7 @@ def ensure_directory(path, follow, recurse, timestamps):
     if prev_state == 'absent':
         # Create directory and assign permissions to it
         if module.check_mode:
-            return {'changed': True, 'diff': diff}
+            return {'path': path, 'changed': True, 'diff': diff}
         curpath = ''
 
         try: