From 1d8a60083c6d5d330e8c6fb90564b422bc1b495e Mon Sep 17 00:00:00 2001
From: Martin Renvoize <martin.renvoize@openfifth.co.uk>
Date: Mon, 13 Apr 2026 11:07:15 +0100
Subject: [PATCH] Bug 39516: (follow-up) Add missing POD for private
 subroutines

Adds minimal POD stubs for all private (underscore-prefixed) subroutines
in C4/Matcher.pm and C4/ImportBatch.pm to satisfy the QA script's
pod_coverage check.

Sponsored-by: Main Library Alliance <https://www.mainlib.org/>
Signed-off-by: Jeanne Mauriello <jeanne.mauriello@mainlib.org>
Signed-off-by: Andrew Fuerste Henry <andrew@bywatersolutions.com>
Signed-off-by: Lucas Gass <lucas@bywatersolutions.com>
---
 C4/ImportBatch.pm | 78 +++++++++++++++++++++++++++++++++++++++++++++++
 C4/Matcher.pm     | 42 +++++++++++++++++++------
 2 files changed, 110 insertions(+), 10 deletions(-)

diff --git a/C4/ImportBatch.pm b/C4/ImportBatch.pm
index e284e30779..32efd2deee 100644
--- a/C4/ImportBatch.pm
+++ b/C4/ImportBatch.pm
@@ -1719,6 +1719,16 @@ sub RecordsFromMarcPlugin {
 
 # internal functions
 
+=head2 _create_import_record
+
+  my $import_record_id = _create_import_record($batch_id, $record_sequence,
+                             $marc_record, $record_type, $encoding, $marc_type);
+
+Inserts a new row into C<import_records> for the given MARC record and returns
+the new C<import_record_id>.
+
+=cut
+
 sub _create_import_record {
     my ( $batch_id, $record_sequence, $marc_record, $record_type, $encoding, $marc_type ) = @_;
 
@@ -1737,6 +1747,15 @@ sub _create_import_record {
     return $import_record_id;
 }
 
+=head2 _add_auth_fields
+
+  _add_auth_fields($import_record_id, $marc_record);
+
+Extracts authority-specific fields from C<$marc_record> and stores them
+in C<import_auths>.
+
+=cut
+
 sub _add_auth_fields {
     my ( $import_record_id, $marc_record ) = @_;
 
@@ -1752,6 +1771,15 @@ sub _add_auth_fields {
     $sth->finish();
 }
 
+=head2 _add_biblio_fields
+
+  _add_biblio_fields($import_record_id, $marc_record);
+
+Extracts bibliographic fields (title, author, ISBN) from C<$marc_record> and
+inserts them into C<import_biblios>.
+
+=cut
+
 sub _add_biblio_fields {
     my ( $import_record_id, $marc_record ) = @_;
 
@@ -1767,6 +1795,15 @@ sub _add_biblio_fields {
 
 }
 
+=head2 _update_biblio_fields
+
+  _update_biblio_fields($import_record_id, $marc_record);
+
+Updates the C<import_biblios> row for an already-staged bibliographic record
+with freshly parsed field values.
+
+=cut
+
 sub _update_biblio_fields {
     my ( $import_record_id, $marc_record ) = @_;
 
@@ -1786,6 +1823,16 @@ sub _update_biblio_fields {
     $sth->finish();
 }
 
+=head2 _parse_biblio_fields
+
+  my ($title, $author, $isbn, $issn, $lccn, $biblionumber) =
+      _parse_biblio_fields($marc_record);
+
+Extracts key bibliographic fields from a MARC::Record object and returns
+them as a list.
+
+=cut
+
 sub _parse_biblio_fields {
     my ($marc_record) = @_;
 
@@ -1800,6 +1847,15 @@ sub _parse_biblio_fields {
 
 }
 
+=head2 _update_batch_record_counts
+
+  _update_batch_record_counts($batch_id);
+
+Recalculates and updates the record-count summary columns on the
+C<import_batches> row for C<$batch_id>.
+
+=cut
+
 sub _update_batch_record_counts {
     my ($batch_id) = @_;
 
@@ -1828,6 +1884,18 @@ sub _update_batch_record_counts {
     );
 }
 
+=head2 _get_commit_action
+
+  my ($biblio_action, $item_action, $match_id) =
+      _get_commit_action($overlay_action, $nomatch_action, $item_action,
+                         $overlay_status, $import_record_id, $record_type);
+
+Determines the appropriate commit action (C<create_new>, C<replace>,
+C<ignore>) for a record based on the batch overlay/nomatch settings and
+the record's current overlay status.
+
+=cut
+
 sub _get_commit_action {
     my ( $overlay_action, $nomatch_action, $item_action, $overlay_status, $import_record_id, $record_type ) = @_;
 
@@ -1868,6 +1936,16 @@ sub _get_commit_action {
     }
 }
 
+=head2 _get_revert_action
+
+  my ($bib_result, $item_result) =
+      _get_revert_action($overlay_action, $overlay_status, $status);
+
+Determines the appropriate revert action for a record based on the batch
+overlay action and the record's current overlay/import status.
+
+=cut
+
 sub _get_revert_action {
     my ( $overlay_action, $overlay_status, $status ) = @_;
 
diff --git a/C4/Matcher.pm b/C4/Matcher.pm
index fa9ef8970c..36fce6f5ee 100644
--- a/C4/Matcher.pm
+++ b/C4/Matcher.pm
@@ -206,7 +206,10 @@ sub fetch {
 
 =head3 _fetch_matchpoint
 
-helper function that retrieves a matchpoint and its components from the DB
+  my $matchpoint = $self->_fetch_matchpoint($matchpoint_id);
+
+Loads a matchpoint and its components from the database and returns a
+hashref with C<index>, C<score>, and C<components>.
 
 =cut
 
@@ -279,8 +282,10 @@ sub store {
 
 =head3 _del_matcher_components
 
-helper function that deletes matchpoints and matchchecks for a matcher;
-used to clear existing values before saving new ones
+  $self->_del_matcher_components();
+
+Deletes all matchpoint component and norm rows for the current matcher
+from the database (used before re-saving).
 
 =cut
 
@@ -300,7 +305,9 @@ sub _del_matcher_components {
 
 =head3 _update_marc_matchers
 
-helper function that updates a MARC matcher DB entry
+  $self->_update_marc_matchers();
+
+Updates the C<marc_matchers> row for the current matcher object.
 
 =cut
 
@@ -324,7 +331,9 @@ sub _update_marc_matchers {
 
 =head3 _new_marc_matchers
 
-helper function that inserts a new MARC matcher entry
+  $self->_new_marc_matchers();
+
+Inserts a new row into C<marc_matchers> and sets C<$self-E<gt>{'id'}>.
 
 =cut
 
@@ -343,7 +352,9 @@ sub _new_marc_matchers {
 
 =head3 _store_matcher_components
 
-helper function that stores the values for matchpoints and matchchecks for a matcher
+  $self->_store_matcher_components($matchpoint_id, \@components);
+
+Persists the component and norm rows for a matchpoint to the database.
 
 =cut
 
@@ -376,7 +387,9 @@ sub _store_matcher_components {
 
 =head3 _store_matchpoint
 
-helper function that stores a matchpoint and its components
+  my $matchpoint_id = $self->_store_matchpoint($matchpoint);
+
+Inserts a matchpoint record into the database and returns its new ID.
 
 =cut
 
@@ -893,7 +906,10 @@ sub dump {
 
 =head3 _passes_required_checks
 
-helper function that checks the match keys for all matched records
+  my $ok = _passes_required_checks($source_record, $target_record, \@matchchecks);
+
+Returns true if the candidate C<$target_record> passes all required field
+equality checks against C<$source_record>.
 
 =cut
 
@@ -913,7 +929,10 @@ sub _passes_required_checks {
 
 =head3 _get_match_keys
 
-helper function that retrieves the values of the match fields from a source record
+  my @keys = _get_match_keys($source_record, $matchpoint);
+
+Extracts and normalises the set of match key strings from C<$source_record>
+for the given C<$matchpoint> definition.
 
 =cut
 
@@ -1009,7 +1028,10 @@ sub _get_match_keys {
 
 =head3 _parse_match_component
 
-helper function to transform a match component into the expected form
+  my $component = _parse_match_component($input_component);
+
+Parses a matchpoint component definition hashref and returns a normalised
+component structure including tag, subfields, offset, length, and norms.
 
 =cut