From d017e2f7c412001677b2cec08781977d5935e8ee Mon Sep 17 00:00:00 2001
From: Alex Arnaud <alex.arnaud@biblibre.com>
Date: Wed, 13 Mar 2019 15:14:31 +0100
Subject: [PATCH] Bug 22358: Add POD to Koha::SharedContent

Signed-off-by: Liz Rea <wizzyrea@gmail.com>
Signed-off-by: Mark Tompsett <mtompset@hotmail.com>
Signed-off-by: Nick Clemens <nick@bywatersolutions.com>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
(cherry picked from commit c6540d1b72d45b2682860fc50716b0d74e3f5e2c)
Signed-off-by: Fridolin Somers <fridolin.somers@biblibre.com>
---
 Koha/SharedContent.pm | 61 +++++++++++++++++++++++++++++++++++--------
 1 file changed, 50 insertions(+), 11 deletions(-)

diff --git a/Koha/SharedContent.pm b/Koha/SharedContent.pm
index 7145e950c3..f1100c0e8a 100644
--- a/Koha/SharedContent.pm
+++ b/Koha/SharedContent.pm
@@ -26,15 +26,23 @@ use Koha::Serials;
 use Koha::Reports;
 use C4::Context;
 
-=head1 DESCRIPTION
+=head1 SharedContent
+
+Koha::SharedContent - Set of methods to quering Mana KB server
 
-Package for accessing shared content via Mana
+=head1 DESCRIPTION
 
-=head2 Package Functions
+Package for accessing shared content via Mana KB. Methods here are intended
+to build and process queries for requesting Mana KB server.
 
 =cut
 
-=head3 process_request
+=head2 process_request
+
+Koha::SharedContent::process_request($request);
+
+Send a request to Mana KB server. URL is defined in koha-conf.xml in mana_config
+tag. $request parameter must be a HTTP::Request object. See build_request method.
 
 =cut
 
@@ -63,7 +71,12 @@ sub process_request {
     return $result ;
 }
 
-=head3 increment_entity_value
+=head2 increment_entity_value
+
+Koha::SharedContent::increment_entity_value($entity_type, $mana_entity_id, $field);
+
+Increment of 1 the field $field of a Mana entity. I.e, this is used to count the number
+of Koha instance using a specific entity.
 
 =cut
 
@@ -71,7 +84,11 @@ sub increment_entity_value {
     return process_request(build_request('increment', @_));
 }
 
-=head3 send_entity
+=head2 send_entity
+
+my $result = Koha::SharedContent::send_entity($language, $borrowernumber, $mana_entity_id, $entity_type);
+
+Share a Koha entity (i.e subscription or report) to Mana KB.
 
 =cut
 
@@ -92,7 +109,11 @@ sub send_entity {
     return $result;
 }
 
-=head3 prepare_entity_data
+=head2 prepare_entity_data
+
+$data = prepare_entity_data($language, $borrowernumber, $mana_entity_id, $entity_type);
+
+Prepare Koha entity data to be sent to Mana KB.
 
 =cut
 
@@ -126,7 +147,12 @@ sub prepare_entity_data {
     return $ressource_mana_info;
 }
 
-=head3 get_entity_by_id
+=head2 get_entity_by_id
+
+my $entity = Koha::SharedContent::get_entity_by_id($entity_type, $mana_entity_id, [{usecomments => 1}]);
+
+Retrieve a Mana entity to be imported into Koha. Add {usecomments => 1} to tell Mana to
+embed all user reviews.
 
 =cut
 
@@ -134,7 +160,12 @@ sub get_entity_by_id {
     return process_request(build_request('getwithid', @_));
 }
 
-=head3 search_entities
+=head2 search_entities
+
+my $result = Koha::SharedContent::search_entities( $entity_type, $search_params );
+my $entities = $result->{data};
+
+Search entities on ManaKB.
 
 =cut
 
@@ -142,7 +173,11 @@ sub search_entities {
     return process_request(build_request('get', @_));
 }
 
-=head3 build_request
+=head2 build_request
+
+$request = build_request($mana_method, [$param1, $param2, ...]);
+
+Create a HTTP::Request object to be passed to process_request.
 
 =cut
 
@@ -201,7 +236,11 @@ sub build_request {
     }
 }
 
-=head3 get_sharing_url
+=head2 get_sharing_url
+
+my $mana_url = get_sharing_url();
+
+Get the Mana KB server URL set in koha config file.
 
 =cut
 
-- 
2.39.5