From 021191bfb65bfc174f0385891d0e6ebab0106ca3 Mon Sep 17 00:00:00 2001
From: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Date: Wed, 26 Jun 2024 15:24:01 +0100
Subject: [PATCH] Bug 37198: Improve GetPreparedLetter documentation

Signed-off-by: Katrin Fischer <katrin.fischer@bsz-bw.de>
(cherry picked from commit 149412cb62a074ccdef1e1c2bbbd2bee35c48498)
Signed-off-by: Lucas Gass <lucas@bywatersolutions.com>
(cherry picked from commit 84814bbef33ac9c04b12cb3f063b2a11cfd0b2ce)
Signed-off-by: Fridolin Somers <fridolin.somers@biblibre.com>
Signed-off-by: wainuiwitikapark <wainuiwitikapark@catalyst.net.nz>
---
 C4/Letters.pm | 42 ++++++++++++++++++++++++------------------
 1 file changed, 24 insertions(+), 18 deletions(-)

diff --git a/C4/Letters.pm b/C4/Letters.pm
index ecfadfbb32..c46ff0769a 100644
--- a/C4/Letters.pm
+++ b/C4/Letters.pm
@@ -541,24 +541,30 @@ sub SendAlerts {
 
 =head2 GetPreparedLetter( %params )
 
-    %params hash:
-      module => letter module, mandatory
-      letter_code => letter code, mandatory
-      branchcode => for letter selection, if missing default system letter taken
-      tables => a hashref with table names as keys. Values are either:
-        - a scalar - primary key value
-        - an arrayref - primary key values
-        - a hashref - full record
-      substitute => custom substitution key/value pairs
-      repeat => records to be substituted on consecutive lines:
-        - an arrayref - tries to guess what needs substituting by
-          taking remaining << >> tokensr; not recommended
-        - a hashref token => @tables - replaces <token> << >> << >> </token>
-          subtemplate for each @tables row; table is a hashref as above
-      want_librarian => boolean,  if set to true triggers librarian details
-        substitution from the userenv
-    Return value:
-      letter fields hashref (title & content useful)
+    my $letter = GetPreparedLetter(
+        {
+            module      => "letter module",           # mandatory
+            letter_code => "letter code",             # mandatory
+            branchcode  => "for letter selection",    # if missing default system letter taken
+            objects     => {},                        # a hashref with object names as keys and objects as values
+            tables      => {},                        # a hashref with table names as keys. Values are either:
+                                                      #  - a scalar - primary key value
+                                                      #  - an arrayref - primary key values
+                                                      #  - a hashref - full record
+            substitute  => {},                        # custom substitution key/value pairs
+            repeat      => '',                        # records to be substituted on consecutive lines, accepts either:
+                                                      #  - an arrayref
+                                                      #    tries to guess what needs substituting by taking remaining
+                                                      #    << >> tokensr; not recommended
+                                                      #  - a hashref token => @tables
+                                                      #    replaces <token> << >> << >> </token> subtemplate for each
+                                                      #    @tables row; table is a hashref as above
+            want_librarian => ''                      # boolean,  if set to true triggers librarian details substitution
+                                                      # from the userenv
+        }
+    );
+
+Return value: letter fields hashref (title & content useful)
 
 =cut
 
-- 
2.39.5