Improving the RETURN and its docs on the apt_repository module (#79658)

* Improving the documentation on how we generate the default value of the filename parameter

* fix pep8

* removing unnecessary documentation and improving the module's return

* making the RETURN docs

* pep8

* version_added and changelog

* module._diff

* module._diff fix

* add rudimentary tests for new outputs

---------

Co-authored-by: Matt Davis <mrd@redhat.com>

changelogs/fragments/79658-improving-return-and-docs.yaml

@@ -0,0 +1,2 @@
+minor_changes:
+  - apt_repository - adds ``sources_added`` and ``sources_removed`` to the return of the module (https://github.com/ansible/ansible/issues/79306).

lib/ansible/modules/apt_repository.py

@@ -146,7 +146,27 @@ EXAMPLES = '''
         state: present
 '''
 
-RETURN = '''#'''
+RETURN = '''
+repo:
+  description: A source string for the repository
+  returned: always
+  type: str
+  sample: "deb https://artifacts.elastic.co/packages/6.x/apt stable main"
+
+sources_added:
+  description: List of sources added
+  returned: success, sources were added
+  type: list
+  sample: ["/etc/apt/sources.list.d/artifacts_elastic_co_packages_6_x_apt.list"]
+  version_added: "2.15"
+
+sources_removed:
+  description: List of sources removed
+  returned: success, sources were removed
+  type: list
+  sample: ["/etc/apt/sources.list.d/artifacts_elastic_co_packages_6_x_apt.list"]
+  version_added: "2.15"
+'''
 
 import copy
 import glob
@@ -688,15 +708,18 @@ def main():
     sources_after = sourceslist.dump()
     changed = sources_before != sources_after
 
-    if changed and module._diff:
-        diff = []
-        for filename in set(sources_before.keys()).union(sources_after.keys()):
-            diff.append({'before': sources_before.get(filename, ''),
-                         'after': sources_after.get(filename, ''),
-                         'before_header': (filename, '/dev/null')[filename not in sources_before],
-                         'after_header': (filename, '/dev/null')[filename not in sources_after]})
-    else:
-        diff = {}
+    diff = []
+    sources_added = set()
+    sources_removed = set()
+    if changed:
+        sources_added = set(sources_after.keys()).difference(sources_before.keys())
+        sources_removed = set(sources_before.keys()).difference(sources_after.keys())
+        if module._diff:
+            for filename in set(sources_added.union(sources_removed)):
+                diff.append({'before': sources_before.get(filename, ''),
+                             'after': sources_after.get(filename, ''),
+                             'before_header': (filename, '/dev/null')[filename not in sources_before],
+                             'after_header': (filename, '/dev/null')[filename not in sources_after]})
 
     if changed and not module.check_mode:
         try:
@@ -728,7 +751,7 @@ def main():
             revert_sources_list(sources_before, sources_after, sourceslist_before)
             module.fail_json(msg=to_native(ex))
 
-    module.exit_json(changed=changed, repo=repo, state=state, diff=diff)
+    module.exit_json(changed=changed, repo=repo, sources_added=sources_added, sources_removed=sources_removed, state=state, diff=diff)
 
 
 if __name__ == '__main__':

test/integration/targets/apt_repository/tasks/apt.yml

@@ -152,6 +152,11 @@
       - 'result.changed'
       - 'result.state == "present"'
       - 'result.repo == "{{test_ppa_spec}}"'
+      - '"sources_added" in result'
+      - 'result.sources_added | length == 1'
+      - '"git" in result.sources_added[0]'
+      - '"sources_removed" in result'
+      - 'result.sources_removed | length == 0'
       - result_cache is not changed
 
 - name: 'examine apt cache mtime'
@@ -167,6 +172,17 @@
   apt_repository: repo='{{test_ppa_spec}}' state=absent
   register: result
 
+- assert:
+    that:
+      - 'result.changed'
+      - 'result.state == "absent"'
+      - 'result.repo == "{{test_ppa_spec}}"'
+      - '"sources_added" in result'
+      - 'result.sources_added | length == 0'
+      - '"sources_removed" in result'
+      - 'result.sources_removed | length == 1'
+      - '"git" in result.sources_removed[0]'
+
 # When installing a repo with the spec, the key is *NOT* added
 - name: 'ensure ppa key is absent (expect: pass)'
   apt_key: id='{{test_ppa_key}}' state=absent