From b488199c353140a3c226aebb449c13a80f07bb4a Mon Sep 17 00:00:00 2001
From: Moray Jones <moray@mysociety.org>
Date: Tue, 16 Jul 2024 12:14:17 +0100
Subject: [PATCH] [Bexley] Add POD documentation to Bexley-related packages

---
 perllib/BexleyAddresses.pm                  | 43 +++++++++++
 perllib/FixMyStreet/Cobrand/Bexley.pm       | 81 +++++++++++++++++++--
 perllib/FixMyStreet/Cobrand/Bexley/Waste.pm | 33 ++++++++-
 3 files changed, 148 insertions(+), 9 deletions(-)

diff --git a/perllib/BexleyAddresses.pm b/perllib/BexleyAddresses.pm
index cffb24bdf7d..77a0d561f92 100644
--- a/perllib/BexleyAddresses.pm
+++ b/perllib/BexleyAddresses.pm
@@ -1,3 +1,33 @@
+=head1 NAME
+
+BexleyAddresses - handles address lookup for Bexley WasteWorks.
+
+=head1 SYNOPSIS
+
+Bexley provide us with a CSV file of LLPG (Local Land and Property Gazetteer) data which we pull into an SQLite database file.
+
+This is done by running the CSV on C<bin/bexley/make-bexley-ww-postcode-db>.
+
+That script shows the setup of the database in more detail, but to explain briefly, there are three tables:
+
+=over 4
+
+=item * postcodes
+
+Stores postcode, UPRN, USRN, and address portions (e.g. house number and name) for each property (properties are uniquely identified by their UPRN)
+
+=item * street_descriptors
+
+Stores address data (e.g. street & town name) for each USRN (street identifier)
+
+=item * child_uprns
+
+Captures mapping between parent and child properties (e.g. if a building contains multiple flats, the building is the parent, the children are the flats)
+
+=back
+
+=cut
+
 package BexleyAddresses;
 
 use strict;
@@ -7,6 +37,12 @@ use DBI;
 use FixMyStreet;
 use mySociety::PostcodeUtil;
 
+=head2 database_file
+
+Database is in C<../data/bexley-ww-postcodes.sqlite>
+
+=cut
+
 sub database_file {
     FixMyStreet->path_to('../data/bexley-ww-postcodes.sqlite');
 }
@@ -18,6 +54,13 @@ sub connect_db {
         undef, undef );
 }
 
+=head2 addresses_for_postcode
+
+We only fetch child addresses. These are displayed in a dropdown after user
+has input a postcode.
+
+=cut
+
 sub addresses_for_postcode {
     my $postcode = shift;
 
diff --git a/perllib/FixMyStreet/Cobrand/Bexley.pm b/perllib/FixMyStreet/Cobrand/Bexley.pm
index 722069de440..ca051793e33 100644
--- a/perllib/FixMyStreet/Cobrand/Bexley.pm
+++ b/perllib/FixMyStreet/Cobrand/Bexley.pm
@@ -1,3 +1,15 @@
+=head1 NAME
+
+FixMyStreet::Cobrand::Bexley - code specific to the Bexley Cobrand
+
+=head1 SYNOPSIS
+
+Bexley is an FMS integration with Confirm, Uniform and Symology backends.
+
+Also has a waste integration with Whitespace in L<FixMyStreet::Cobrand::Bexley::Waste>.
+
+=cut
+
 package FixMyStreet::Cobrand::Bexley;
 use parent 'FixMyStreet::Cobrand::Whitelabel';
 
@@ -13,8 +25,38 @@ sub council_area_id { 2494 }
 sub council_area { 'Bexley' }
 sub council_name { 'London Borough of Bexley' }
 sub council_url { 'bexley' }
+
+=head2 Defaults
+
+=over 4
+
+=cut
+
+=item * Admin user domain is C<bexley.gov.uk>
+
+=cut
+
+sub admin_user_domain { 'bexley.gov.uk' }
+
+=item * Bexley uses its own geocoder (L<FixMyStreet::Geocode::Bexley>)
+
+Bexley provides a layer containing street names that
+supplements the standard geocoder
+
+=cut
+
 sub get_geocoder { 'Bexley' }
+
+=item * It has a default map zoom of 4
+
+=cut
+
 sub default_map_zoom { 4 }
+
+=item * It doesn't sent questionnaires to reporters
+
+=cut
+
 sub send_questionnaires { 0 }
 
 sub disambiguate_location {
@@ -28,6 +70,13 @@ sub disambiguate_location {
     };
 }
 
+=item * It overrides Dartford border postcodes
+
+Allows starting to make a report if postcode is in Dartford
+on the border
+
+=cut
+
 sub geocode_postcode {
     my ( $self, $s ) = @_;
 
@@ -42,11 +91,16 @@ sub geocode_postcode {
     return $self->next::method($s);
 }
 
+=item * Report resending
+
+Report resend button is disabled. But we can resend reports upon category change, unless it will be going to the
+same Symology database, because that will reject saying it already has the
+ID.
+
+=cut
+
 sub disable_resend_button { 1 }
 
-# We can resend reports upon category change, unless it will be going to the
-# same Symology database, because that will reject saying it already has the
-# ID.
 sub category_change_force_resend {
     my ($self, $old, $new) = @_;
 
@@ -62,6 +116,21 @@ sub category_change_force_resend {
     return ($old =~ /^StreetLighting/ xor $new =~ /^StreetLighting/);
 }
 
+=item * Only show open reports on map page
+
+=back
+
+=cut
+
+sub on_map_default_status { 'open' }
+
+=head2 munge_report_new_category_list
+
+For some categories Bexley staff use a different URL
+from the public in the notices
+
+=cut
+
 sub munge_report_new_category_list {
     my ($self, $options, $contacts, $extras) = @_;
 
@@ -79,8 +148,6 @@ sub munge_report_new_category_list {
     }
 }
 
-sub on_map_default_status { 'open' }
-
 sub open311_munge_update_params {
     my ($self, $params, $comment, $body) = @_;
 
@@ -189,8 +256,6 @@ sub open311_extra_data_include {
     return $open311_only;
 }
 
-sub admin_user_domain { 'bexley.gov.uk' }
-
 sub open311_post_send {
     my ($self, $row, $h, $sender) = @_;
 
@@ -374,7 +439,7 @@ sub dashboard_export_problems_add_columns {
 
 =head2 waste_auto_confirm_report
 
-Missed collection reports are automatically confirmed.
+Missed collection reports are automatically confirmed
 
 =cut
 
diff --git a/perllib/FixMyStreet/Cobrand/Bexley/Waste.pm b/perllib/FixMyStreet/Cobrand/Bexley/Waste.pm
index 31fd04d7f12..7ea80543dc2 100644
--- a/perllib/FixMyStreet/Cobrand/Bexley/Waste.pm
+++ b/perllib/FixMyStreet/Cobrand/Bexley/Waste.pm
@@ -1,3 +1,15 @@
+=head1 NAME
+
+FixMyStreet::Cobrand::Bexley::Waste - code specific to Bexley WasteWorks
+
+=head1 SYNOPSIS
+
+Bexley integrates with Whitespace for its waste data.
+
+Address lookup is handled in L<BexleyAddresses>.
+
+=cut
+
 package FixMyStreet::Cobrand::Bexley::Waste;
 
 use Moo::Role;
@@ -16,9 +28,28 @@ has 'whitespace' => (
     default => sub { Integrations::Whitespace->new(%{shift->feature('whitespace')}) },
 );
 
+=head2 Constants
+
+=over 4
+
+=cut
+
+=item * WORKING_DAYS_WINDOW
+
+Recent collections are defined as being 3 or fewer working days ago.
+
+=cut
+
 use constant WORKING_DAYS_WINDOW => 3;
 
-# 0001-01-01T00:00:00 represents an undefined date
+=item * WHITESPACE_UNDEF_DATE
+
+C<0001-01-01T00:00:00> represents an undefined date in Whitespace.
+
+=back
+
+=cut
+
 use constant WHITESPACE_UNDEF_DATE => '0001-01-01T00:00:00';
 
 sub waste_fetch_events {