Update file.py's help doc, and narrow down diff logic, for recent pull 56353 (#59069)

* Limiting when path_content is generated

path_content will be empty and unnecessary in all scenarios except when changing the state of a folder to absent, so adding in a check to limit when this parameter is defined

lib/ansible/modules/files/file.py

@@ -33,7 +33,8 @@ options:
   state:
     description:
     - If C(absent), directories will be recursively deleted, and files or symlinks will
-      be unlinked. Note that C(absent) will not cause C(file) to fail if the C(path) does
+      be unlinked. In the case of a directory, if C(diff) is declared, you will see the files and folders deleted listed
+      under C(path_contents). Note that C(absent) will not cause C(file) to fail if the C(path) does
       not exist as the state did not change.
     - If C(directory), all intermediate subdirectories will be created if they
       do not exist. Since Ansible 1.7 they will be created with the supplied permissions.
@@ -377,7 +378,7 @@ def initial_diff(path, state, prev_state):
     if prev_state != state:
         diff['before']['state'] = prev_state
         diff['after']['state'] = state
-        if state == 'absent':
+        if state == 'absent' and prev_state == 'directory':
             walklist = {
                 'directories': [],
                 'files': [],

test/integration/targets/file/tasks/main.yml

@@ -266,21 +266,25 @@
 
 - name: check what would be removed if folder state was absent and diff is enabled
   file: 
-    path: "{{ output_dir }}"
+    path: "{{ item }}"
     state: absent
   check_mode: yes
   diff: yes
+  with_items:
+    - "{{ output_dir }}"
+    - "{{ output_dir }}/foobar/fileA"
   register: folder_absent_result
 
-- name: assert that the absent check lists expected files and folders
+- name: 'assert that the "absent" state lists expected files and folders for only directories'
   assert:
     that:
-      - folder_absent_result.diff.before.path_content is defined
-      - test_folder in folder_absent_result.diff.before.path_content.directories
-      - test_file in folder_absent_result.diff.before.path_content.files
+      - folder_absent_result.results[0].diff.before.path_content is defined
+      - folder_absent_result.results[1].diff.before.path_content is not defined
+      - test_folder in folder_absent_result.results[0].diff.before.path_content.directories
+      - test_file in folder_absent_result.results[0].diff.before.path_content.files
   vars:
-    test_folder: "{{ folder_absent_result.path }}/foobar"
-    test_file: "{{ folder_absent_result.path }}/foobar/fileA"
+    test_folder: "{{ folder_absent_result.results[0].path }}/foobar"
+    test_file: "{{ folder_absent_result.results[0].path }}/foobar/fileA"
 
 - name: Change ownership of a directory with recurse=no(default)
   file: path={{output_dir}}/foobar owner=1234