From 7fb5a16066088f34ac7e8e990ea802f2a3ca5c7a Mon Sep 17 00:00:00 2001 From: Jonathan Druart Date: Wed, 23 Apr 2025 16:53:23 +0200 Subject: [PATCH] Bug 39705: Ask AI to write POD for C4::Circulation --- C4/Circulation.pm | 337 +++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 317 insertions(+), 20 deletions(-) diff --git a/C4/Circulation.pm b/C4/Circulation.pm index 60dc4dc765e..a48930621da 100644 --- a/C4/Circulation.pm +++ b/C4/Circulation.pm @@ -419,7 +419,44 @@ sub transferbook { =head2 TooMany -Missing POD for TooMany. + my $result = TooMany($patron, $item, $params); + +Check if a patron has too many items checked out according to circulation rules. +This function checks both item-type specific rules and branch-level rules. + +=over 4 + +=item Parameters + +=over 8 + +=item C<$patron> + +A Koha::Patron object representing the patron. + +=item C<$item> + +A Koha::Item object representing the item to be checked out. + +=item C<$params> + +A hashref containing: +- onsite_checkout: Boolean indicating if this is an onsite checkout +- switch_onsite_checkout: Boolean indicating if this is switching to an onsite checkout + +=back + +=item Returns + +A hashref containing: +- reason: The reason why the checkout is not allowed (e.g., 'TOO_MANY', 'TOO_MANY_ONSITE') +- max_allowed: The maximum number of items allowed +- current: The current number of items checked out +- count: The number of items over the limit + +Returns undef if the checkout is allowed. + +=back =cut @@ -1414,17 +1451,37 @@ sub CanBookBeReturned { return ( $allowed, $message ); } -=head2 CheckHighHolds +=head2 checkHighHolds - used when syspref decreaseLoanHighHolds is active. Returns 1 or 0 to define whether the minimum value held in - decreaseLoanHighHoldsValue is exceeded, the total number of outstanding holds, the number of days the loan - has been decreased to (held in syspref decreaseLoanHighHoldsValue), and the new due date + my $result = checkHighHolds($item, $patron); -=cut +Check if an item has a high number of holds and determine if the loan period should be reduced. -=head2 checkHighHolds +=over 4 + +=item Parameters + +=over 8 + +=item C<$item> + +A Koha::Item object representing the item to be checked out. + +=item C<$patron> -Missing POD for checkHighHolds. +A Koha::Patron object representing the patron. + +=back + +=item Returns + +A hashref containing: +- exceeded: Boolean indicating if the holds threshold is exceeded +- outstanding: Number of outstanding holds on the item +- duration: The reduced loan duration if applicable +- due_date: The reduced due date if applicable + +=back =cut @@ -3547,7 +3604,22 @@ sub AddRenewal { =head2 GetRenewCount -Missing POD for GetRenewCount. + my ($renewcount, $renewsallowed, $renewsleft, $unseencount, $unseenallowed, $unseenleft) = GetRenewCount($borrowernumber_or_patron, $itemnumber_or_item); + +Get the renewal counts and limits for a patron and item. + +Parameters: + $borrowernumber_or_patron - Either a borrowernumber or a Koha::Patron object + $itemnumber_or_item - Either an itemnumber or a Koha::Item object + +Returns: + A list of six values: + - $renewcount - Number of times the item has been renewed + - $renewsallowed - Maximum number of renewals allowed + - $renewsleft - Number of renewals remaining + - $unseencount - Number of unseen renewals used + - $unseenallowed - Maximum number of unseen renewals allowed + - $unseenleft - Number of unseen renewals remaining =cut @@ -4174,7 +4246,15 @@ sub CalcDateDue { =head2 CheckValidBarcode -Missing POD for CheckValidBarcode. + my $exists = CheckValidBarcode($barcode); + +Check if a barcode exists in the items table. + +Parameters: + $barcode - The barcode to check + +Returns: + The count of items with this barcode (1 if exists, 0 if not) =cut @@ -4269,7 +4349,28 @@ sub DeleteBranchTransferLimits { =head2 ReturnLostItem -Missing POD for ReturnLostItem. + ReturnLostItem($borrowernumber, $itemnum); + +Mark a lost item as returned. This is a wrapper around MarkIssueReturned that specifically +handles the return of items that were previously marked as lost. + +=over 4 + +=item Parameters + +=over 8 + +=item C<$borrowernumber> + +The borrower number of the patron who had the item checked out. + +=item C<$itemnum> + +The item number of the lost item being returned. + +=back + +=back =cut @@ -4362,7 +4463,20 @@ sub LostItem { =head2 GetOfflineOperations -Missing POD for GetOfflineOperations. + my $operations = GetOfflineOperations(); + +Retrieve all pending offline operations for the current branch. + +Returns: + An array reference of hash references containing pending offline operations: + - operationid + - userid + - branchcode + - timestamp + - action + - barcode + - cardnumber + - amount =cut @@ -4376,7 +4490,24 @@ sub GetOfflineOperations { =head2 GetOfflineOperation -Missing POD for GetOfflineOperation. + my $operation = GetOfflineOperation($operationid); + +Retrieve a specific pending offline operation by its ID. + +Parameters: + $operationid - The ID of the operation to retrieve + +Returns: + A hash reference containing the operation details: + - operationid + - userid + - branchcode + - timestamp + - action + - barcode + - cardnumber + - amount + Returns undef if the operation is not found. =cut @@ -4391,7 +4522,20 @@ sub GetOfflineOperation { =head2 AddOfflineOperation -Missing POD for AddOfflineOperation. + my $operationid = AddOfflineOperation($userid, $branchcode, $action, $barcode, $cardnumber, $amount); + +Add a new pending offline operation to the database. + +Parameters: + $userid - The ID of the staff member who created the operation + $branchcode - The branch code where the operation was created + $action - The type of operation (ISSUE, RETURN, PAYMENT) + $barcode - The barcode of the item (for ISSUE/RETURN) or empty string + $cardnumber - The card number of the patron (for ISSUE/RETURN) or empty string + $amount - The amount for payment operations or 0 for other operations + +Returns: + The ID of the newly created operation, or undef on failure. =cut @@ -4407,7 +4551,27 @@ sub AddOfflineOperation { =head2 DeleteOfflineOperation -Missing POD for DeleteOfflineOperation. + my $result = DeleteOfflineOperation($operationid); + +Delete a pending offline operation from the database. + +=over 4 + +=item Parameters + +=over 8 + +=item C<$operationid> + +The ID of the operation to delete. + +=back + +=item Returns + +A string containing "Deleted." on success. + +=back =cut @@ -4420,7 +4584,32 @@ sub DeleteOfflineOperation { =head2 ProcessOfflineOperation -Missing POD for ProcessOfflineOperation. + my $report = ProcessOfflineOperation($operation); + +Process an offline circulation operation that was previously stored in the database. +This function handles three types of operations: returns, issues, and payments. + +=over 4 + +=item Parameters + +=over 8 + +=item C<$operation> + +A hashref containing the operation details: +- action: The type of operation ('return', 'issue', or 'payment') +- operationid: The ID of the operation in the pending_offline_operations table +- barcode: The item barcode (for returns and issues) +- Additional fields specific to each operation type + +=back + +=item Returns + +A report string containing the result of processing the operation. + +=back =cut @@ -4443,7 +4632,32 @@ sub ProcessOfflineOperation { =head2 ProcessOfflineReturn -Missing POD for ProcessOfflineReturn. + my $result = ProcessOfflineReturn($operation); + +Process an offline return operation that was previously stored in the database. + +=over 4 + +=item Parameters + +=over 8 + +=item C<$operation> + +A hashref containing the operation details: +- barcode: The barcode of the item being returned +- timestamp: The timestamp of when the return was recorded + +=back + +=item Returns + +A string containing: +- "Success." if the return was processed successfully +- "Item not issued." if the item was not checked out +- "Item not found." if the item barcode was not found + +=back =cut @@ -4476,7 +4690,33 @@ sub ProcessOfflineReturn { =head2 ProcessOfflineIssue -Missing POD for ProcessOfflineIssue. + my $result = ProcessOfflineIssue($operation); + +Process an offline issue operation that was previously stored in the database. + +=over 4 + +=item Parameters + +=over 8 + +=item C<$operation> + +A hashref containing the operation details: +- barcode: The barcode of the item being issued +- cardnumber: The patron's card number or userid +- timestamp: The timestamp of when the issue was recorded + +=back + +=item Returns + +A string containing: +- "Success." if the issue was processed successfully +- "Barcode not found." if the item barcode was not found +- "Borrower not found." if the patron was not found + +=back =cut @@ -4518,7 +4758,30 @@ sub ProcessOfflineIssue { =head2 ProcessOfflinePayment -Missing POD for ProcessOfflinePayment. + my $result = ProcessOfflinePayment($operation); + +Process an offline payment operation that was previously stored in the database. + +=over 4 + +=item Parameters + +=over 8 + +=item C<$operation> + +A hashref containing the operation details: +- cardnumber: The patron's card number or userid +- amount: The amount to be paid +- branchcode: The branch where the payment was recorded + +=back + +=item Returns + +A string containing "Success." if the payment was processed successfully. + +=back =cut @@ -4697,7 +4960,41 @@ sub GetPendingOnSiteCheckouts { =head2 GetTopIssues -Missing POD for GetTopIssues. + my @top_issues = GetTopIssues($params); + +Get a list of the most frequently issued items based on specified criteria. + +=over 4 + +=item Parameters + +=over 8 + +=item C<$params> + +A hashref containing: +- count: The number of items to return +- branch: The branch code to filter by (optional) +- itemtype: The item type to filter by (optional) +- ccode: The collection code to filter by (optional) +- newness: The number of days since creation to filter by (optional) + +=back + +=item Returns + +An array of hashrefs containing: +- biblionumber: The bibliographic record number +- title: The title of the item +- author: The author of the item +- itemtype: The item type +- publishercode: The publisher code +- place: The place of publication +- publicationyear: The year of publication +- copyrightdate: The copyright date +- pages: The number of pages +- size: The size of the item +- ccode: The collection code =cut -- 2.34.1