From 5b2e49141586d0c169de5a67349cd9785836b8e6 Mon Sep 17 00:00:00 2001
From: Mark Tompsett <mtompset@hotmail.com>
Date: Fri, 9 Mar 2018 11:54:16 +0000
Subject: [PATCH] Bug 18570: (QA follow-up) Improved POD

This tweaks the perldoc for SendQueuedMessages and adds
some for _get_unsent_messages.

TEST PLAN
---------

perldoc C4::Letters
-- look at _add_attachments (ugly), _get_unsent_messages (non-existent),
   SendQueuedMessages (no reference to borrowernumber or letter_code).
apply patch
perldoc C4::Letters
-- confirm that SendQueuedMessages and _get_unsent_messages
   have reasonable POD information.
-- notice how _add_attachments' POD is now readable

run koha qa test tools

Signed-off-by: Julian Maurice <julian.maurice@biblibre.com>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
---
 C4/Letters.pm | 48 +++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 37 insertions(+), 11 deletions(-)

diff --git a/C4/Letters.pm b/C4/Letters.pm
index 841362a169..b76338e0ea 100644
--- a/C4/Letters.pm
+++ b/C4/Letters.pm
@@ -1026,10 +1026,22 @@ ENDSQL
 
 =head2 SendQueuedMessages ([$hashref]) 
 
-    my $sent = SendQueuedMessages({ verbose => 1, limit => 50 });
+    my $sent = SendQueuedMessages({
+        letter_code => $letter_code,
+        borrowernumber => $who_letter_is_for,
+        limit => 50,
+        verbose => 1
+    });
+
+Sends all of the 'pending' items in the message queue, unless
+parameters are passed.
 
-Sends all of the 'pending' items in the message queue, unless the optional
-limit parameter is passed too. The verbose parameter is also optional.
+The letter_code, borrowernumber and limit parameters are used
+to build a parameter set for _get_unsent_messages, thus limiting
+which pending messages will be processed. They are all optional.
+
+The verbose parameter can be used to generate debugging output.
+It is also optional.
 
 Returns number of messages sent.
 
@@ -1229,15 +1241,15 @@ sub ResendMessage {
 
 =head2 _add_attachements
 
-named parameters:
-letter - the standard letter hashref
-attachments - listref of attachments. each attachment is a hashref of:
-  type - the mime type, like 'text/plain'
-  content - the actual attachment
-  filename - the name of the attachment.
-message - a MIME::Lite object to attach these to.
+  named parameters:
+  letter - the standard letter hashref
+  attachments - listref of attachments. each attachment is a hashref of:
+    type - the mime type, like 'text/plain'
+    content - the actual attachment
+    filename - the name of the attachment.
+  message - a MIME::Lite object to attach these to.
 
-returns your letter object, with the content updated.
+  returns your letter object, with the content updated.
 
 =cut
 
@@ -1273,6 +1285,20 @@ sub _add_attachments {
 
 }
 
+=head2 _get_unsent_messages
+
+  This function's parameter hash reference takes the following
+  optional named parameters:
+   message_transport_type: method of message sending (e.g. email, sms, etc.)
+   borrowernumber        : who the message is to be sent
+   letter_code           : type of message being sent (e.g. PASSWORD_RESET)
+   limit                 : maximum number of messages to send
+
+  This function returns an array of matching hash referenced rows from
+  message_queue with some borrower information added.
+
+=cut
+
 sub _get_unsent_messages {
     my $params = shift;
 
-- 
2.39.5