Add POD and other comments

Also removing various TODOs that have been captured elsewhere.

Author: nephila-nacrea

perllib/Integrations/Confirm.pm

@@ -289,9 +289,6 @@ sub perform_request {
     return $response;
 }
 
-# TODO Tests
-# TODO Comments/POD
-
 sub perform_request_graphql {
     my ($self, %args) = @_;
 
@@ -325,12 +322,18 @@ sub perform_request_graphql {
 
     my $content = decode_json($response->content);
 
-    # TODO Error handling
-
     return $content;
 }
 
-# TODO Explain why graphql variables don't work
+# GraphQL queries.
+# Confirm docs: https://help.dudesolutions.com/Content/PDF/Confirm/v21.10/confirm-v21-10-web-api-specification.pdf
+#
+# We use GraphQL to fetch 'job' objects from Confirm.
+# You can read about GraphQL at https://graphql.org/learn/
+# BUT
+# it appears that Confirm's implementation lacks some features, notably
+# variable support (hence the use of string interpolation below). It also
+# tends to ignore faulty filter definitions in favour of fetching everything.
 
 sub job_status_logs_graphql_query {
     my ( $self, %args ) = @_;
@@ -341,8 +344,6 @@ sub job_status_logs_graphql_query {
     my @status_codes
         = keys %{ $self->config->{job_reverse_status_mapping} // () };
 
-    # TODO What if dates not present?
-    # TODO Timezone handling?
     my (
         $start_date,
         $end_date,
@@ -389,8 +390,6 @@ sub job_status_logs_graphql_query {
 GRAPHQL
 }
 
-# TODO In batches?
-
 sub jobs_graphql_query {
     my ( $self, %args ) = @_;
 

perllib/Open311/Endpoint/Integration/Confirm.pm

@@ -67,17 +67,26 @@ has service_whitelist => (
     }
 );
 
-# TODO POD
+=head2 handle_jobs
+
+Whether cobrand fetches jobs from Confirm alongside enquiries. This is
+based on whether the cobrand has provided a GraphQL URL in its config.
+
+=cut
 
-# Whether cobrand also fetches jobs from Confirm alongside enquiries
 has handle_jobs => (
     is => 'lazy',
     default => sub {
         return $_[0]->get_integration->config->{graphql_url} ? 1 : 0;
     }
 );
 
-# TODO POD
+=head2 job_service_whitelist
+
+Controls the mapping of Confirm job service/subject codes to Open311 services
+(as opposed to service_whitelist, which handles enquiry services)
+
+=cut
 
 has job_service_whitelist => (
     is => 'ro',
@@ -242,7 +251,13 @@ has reverse_status_mapping => (
     default => sub { {} }
 );
 
-# TODO POD
+=head2 job_reverse_status_mapping
+
+Maps Confirm job status codes to Open311 service request status codes.
+Used for service request updates which are generated by job updates in
+Confirm, and for job service requests initially fetched from Confirm.
+
+=cut
 
 has job_reverse_status_mapping => (
     is => 'ro',
@@ -910,7 +925,6 @@ sub get_service_requests {
                 next;
             }
 
-            # TODO Can we assume logs are already ordered by date?
             my $last_status_log = $job->{statusLogs}[-1];
 
             my $status = $self->job_reverse_status_mapping