Add documentation for Security::PipelineVulnerabilitiesFinder behaviour

ee/app/finders/security/pipeline_vulnerabilities_finder.rb

@@ -73,6 +73,11 @@ module Security
       end
     end
 
+    # This finder is used for fetching vulnerabilities for any pipeline, if we used it to fetch
+    # vulnerabilities for a non-default-branch, the occurrences will be unpersisted, so we
+    # coerce the POROs into unpersisted AR records to give them a common object.
+    # See https://gitlab.com/gitlab-org/gitlab/issues/33588#note_291849433 for more context
+    # on why this happens.
     def normalize_report_occurrences(report_occurrences, vulnerabilities)
       report_occurrences.map do |report_occurrence|
         occurrence_hash = report_occurrence.to_hash

ee/lib/api/vulnerability_findings.rb

@@ -56,6 +56,11 @@ module API
       get ':id/vulnerability_findings' do
         authorize! :read_vulnerability, user_project
 
+        # We might have to add rubocop:disable annotation here in case
+        # https://gitlab.com/gitlab-org/gitlab/issues/32763 happens, using
+        # Kaminari.paginate_array here is correct
+        # See https://gitlab.com/gitlab-org/gitlab/issues/33588#note_291849433
+        # for discussion
         vulnerability_occurrences = paginate(
           Kaminari.paginate_array(
             vulnerability_occurrences_by(declared_params)