Update docs for report grouping.

Author: bmedx

docs/static_search.rst

@@ -46,6 +46,9 @@ annotations, grouped by file. Each annotation entry has the following keys:
         'annotation_data': 'This model contains no PII.',  # The comment, or choices, found with the annotation token
     }
 
+If an annotation is in a group, there will also be a `report_group_id`. This key is unique for each found group,
+allowing tools further down the toolchain to keep them together for presentation.
+
 Extensions can also send back some additional data in an ``extra`` key, if desired. The Django Model Search Tool does
 this to return the Django app and model name.
 

tests/test_base.py

@@ -85,54 +85,58 @@ def test_format_results_for_report():
 
     search = FakeSearch(config)
 
+    # Create a fake result set for _format_results_for_report to work on
     fake_results = OrderedDict()
+
+    # First file has 6 annotations. expected_group_id is a special key for this test, allowing us to loop through
+    # these below and know what group each result should be in.
     fake_results['foo/bar.py'] = [
             {
                 'found_by': 'test',
                 'filename': 'foo/bar.py',
                 'line_number': 1,
                 'annotation_token': 'token2',
-                'annotation_data': 'Group id 1',
+                'annotation_data': 'file 1 annotation 1',
                 'expected_group_id': 1
             },
             {
                 'found_by': 'test',
                 'filename': 'foo/bar.py',
                 'line_number': 2,
                 'annotation_token': 'foo',
-                'annotation_data': 'Group id 1',
+                'annotation_data': 'file 1 annotation 2',
                 'expected_group_id': 1
             },
             {
                 'found_by': 'test',
                 'filename': 'foo/bar.py',
                 'line_number': 4,
                 'annotation_token': 'not_in_a_group',
-                'annotation_data': 'Not in a group',
+                'annotation_data': 'file 1 annotation 3',
                 'expected_group_id': None
             },
             {
                 'found_by': 'test',
                 'filename': 'foo/bar.py',
                 'line_number': 10,
                 'annotation_token': 'token1',
-                'annotation_data': 'Group id 2',
+                'annotation_data': 'file 1 annotation 4',
                 'expected_group_id': 2
             },
             {
                 'found_by': 'test',
                 'filename': 'foo/bar.py',
                 'line_number': 12,
                 'annotation_token': 'token2',
-                'annotation_data': 'Group id 3',
+                'annotation_data': 'file 1 annotation 5',
                 'expected_group_id': 3
             },
             {
                 'found_by': 'test',
                 'filename': 'foo/bar.py',
                 'line_number': 13,
                 'annotation_token': 'foo',
-                'annotation_data': 'Group id 3',
+                'annotation_data': 'file 1 annotation 6',
                 'expected_group_id': 3
             },
         ]
@@ -143,27 +147,31 @@ def test_format_results_for_report():
                 'filename': 'foo/bar.py',
                 'line_number': 1,
                 'annotation_token': 'token2',
-                'annotation_data': 'Group id 1',
+                'annotation_data': 'file 2 annotation 1',
                 'expected_group_id': 4
             },
             {
                 'found_by': 'test',
                 'filename': 'foo/bar.py',
                 'line_number': 2,
                 'annotation_token': 'foo',
-                'annotation_data': 'Group id 1',
+                'annotation_data': 'file 1 annotation 2',
                 'expected_group_id': 4
             }
         ]
 
+    # Run the format function
     results = search._format_results_for_report(fake_results)  # pylint: disable=protected-access
 
     for filename in fake_results:
         for fake in fake_results[filename]:
             for formatted in results[filename]:
+                # When we find the same annotation, make sure that grouping is correct
                 if fake['annotation_data'] == formatted['annotation_data']:
+                    # Ungrouped annotations should not have the 'report_group_id' key
                     if fake['expected_group_id'] is None:
                         assert 'report_group_id' not in formatted
+                    # Otherwise it should match our expected value
                     else:
                         assert fake['expected_group_id'] == formatted['report_group_id']
                     break