From 7f783889fc0e603585a6a22e4b93405d0243d7e0 Mon Sep 17 00:00:00 2001
From: David Gustafsson <david.gustafsson@ub.gu.se>
Date: Fri, 7 Dec 2018 14:32:25 +0100
Subject: [PATCH] Bug 19884: Add documentation for pluralized versions of
 subroutines

---
 C4/Biblio.pm | 117 +++++++++++++++++++++++++++++++++++++++++++++++------------
 C4/Items.pm  |  13 ++++++-
 2 files changed, 106 insertions(+), 24 deletions(-)

diff --git a/C4/Biblio.pm b/C4/Biblio.pm
index 91033fe433..0306dc4722 100644
--- a/C4/Biblio.pm
+++ b/C4/Biblio.pm
@@ -1108,6 +1108,45 @@ sub GetMarcSubfieldStructureFromKohaField {
     return wantarray ? @{$mss->{$kohafield}} : $mss->{$kohafield}->[0];
 }
 
+=head2 GetMarcBiblio
+
+  my $record = GetMarcBiblio({
+      biblionumber => $biblionumber,
+      embed_items  => $embeditems,
+      opac         => $opac,
+      borcat       => $patron_category });
+
+Returns MARC::Record representing a biblio record, or C<undef> if the
+biblionumber doesn't exist.
+
+Both embed_items and opac are optional.
+If embed_items is passed and is 1, items are embedded.
+If opac is passed and is 1, the record is filtered as needed.
+
+=over 4
+
+=item C<$biblionumber>
+
+the biblionumber
+
+=item C<$embeditems>
+
+set to true to include item information.
+
+=item C<$opac>
+
+set to true to make the result suited for OPAC view. This causes things like
+OpacHiddenItems to be applied.
+
+=item C<$borcat>
+
+If the OpacHiddenItemsExceptions system preference is set, this patron category
+can be used to make visible OPAC items which would be normally hidden.
+It only makes sense in combination both embed_items and opac values true.
+
+=back
+
+=cut
 
 sub GetMarcBiblio {
     my ($params) = @_;
@@ -1128,42 +1167,38 @@ sub GetMarcBiblio {
     return $biblio;
 }
 
-=head2 GetMarcBiblio
+=head2 GetMarcBiblios
 
-  my $record = GetMarcBiblio({
-      biblionumber => $biblionumber,
+  my $records = GetMarcBiblio({
+      biblionumbers => $biblionumbers,
       embed_items  => $embeditems,
       opac         => $opac,
       borcat       => $patron_category });
 
-Returns MARC::Record representing a biblio record, or C<undef> if the
-biblionumber doesn't exist.
+Same as L</GetMarcBiblio> but accepts multiple C<biblionumbers>. Returns a
+hashref of C<MARC::Record>s keyed by biblionumbers in scalar context, or a
+list of C<MARC::Records> in list context, or C<undef> if non of the
+biblionumbers exist. Accepts the same arguments as C<GetMarcBiblio>
+but instead of a single C<biblionumber> takes multiple C<biblionumbers> and
+so that only database has to be performed to fetch biblios and biblio items
+respectively. This has a substatial performance gain when a large number of
+biblios is to be fetched.
 
-Both embed_items and opac are optional.
-If embed_items is passed and is 1, items are embedded.
-If opac is passed and is 1, the record is filtered as needed.
+For a more detailed explanation of arguments and behavior see
+L</GetMarcBiblios>.
 
 =over 4
 
-=item C<$biblionumber>
+=item C<$biblionumbers>
 
-the biblionumber
+The biblionumbers to be fetched.
 
 =item C<$embeditems>
 
-set to true to include item information.
-
 =item C<$opac>
 
-set to true to make the result suited for OPAC view. This causes things like
-OpacHiddenItems to be applied.
-
 =item C<$borcat>
 
-If the OpacHiddenItemsExceptions system preference is set, this patron category
-can be used to make visible OPAC items which would be normally hidden.
-It only makes sense in combination both embed_items and opac values true.
-
 =back
 
 =cut
@@ -2798,14 +2833,15 @@ sub ModZebra {
     }
 }
 
-
 =head2 EmbedItemsInMarcBiblio
 
-    EmbedItemsInMarcBiblio({
+    $marc_with_item = EmbedItemsInMarcBiblio({
         marc_record  => $marc,
         biblionumber => $biblionumber,
         item_numbers => $itemnumbers,
-        opac         => $opac });
+        opac         => $opac
+        borcat         => $borcat
+    });
 
 Given a MARC::Record object containing a bib record,
 modify it to include the items attached to it as 9XX
@@ -2839,9 +2875,44 @@ sub EmbedItemsInMarcBiblio {
     return $marc_with_items;
 }
 
+=head2 EmbedItemsInMarcBiblios
+
+    my $marc_records_with_items = EmbedItemsInMarcBiblio({
+        marc_records  => $marc_records,
+        item_numbers => $itemnumbers,
+        opac         => $opac
+        borcat       => $borcat
+    });
+
+Same as L</EmbedItemsInMarcBiblio> but accepts multiple C<$marc_records>.
+
+C<$marc_records> is a hashref of C<MARC::Record>s keyed by biblionumbers.
+
+Returns a hashref on the same format with items embedded.
+
+For a more detailed explanation of arguments and behaviour see
+L</EmbedItemsInMarcbiblio>.
+
+=over 4
+
+=item C<$marc_records>
+
+A hashref of C<MARC::Record>s keyed by biblionumbers for which items should
+be embedded.
+
+=item C<$itemnumbers>
+
+=item C<$opac>
+
+=item C<$borcat>
+
+=back
+
+=cut
+
 sub EmbedItemsInMarcBiblios {
     my ($params) = @_;
-    my ($marc_records, $biblionumber, $itemnumbers, $opac, $borcat);
+    my ($marc_records, $itemnumbers, $opac, $borcat);
     $marc_records = $params->{marc_records};
 
     $itemnumbers = $params->{item_numbers};
diff --git a/C4/Items.pm b/C4/Items.pm
index d94dd61c3d..0644e7e871 100644
--- a/C4/Items.pm
+++ b/C4/Items.pm
@@ -125,7 +125,7 @@ of C<C4::Items>
 
 =head2 GetItem
 
-  $item = GetItem($itemnumber,$barcode,$serial);
+  $item = GetItem($itemnumber, $barcode, $serial);
 
 Return item information, for a given itemnumber or barcode.
 The return value is a hashref mapping item column
@@ -139,6 +139,17 @@ sub GetItem {
     return @{$items} ? $items->[0] : undef;
 }
 
+=head2 GetItem
+
+  $items = GetItem($itemnumbers, $barcode, $serial);
+
+Same as L</GetItem> but accepts multiple C<$itemnumbers>.
+
+For a more detailed explanation of arguments and behavior see
+L</GetItem>.
+
+=cut
+
 =head2 GetItems
 
   $item = GetItems($itemnumber,$barcode,$serial);
-- 
2.11.0