Merge pull request #5087 from roshnaeem/pod

Document the ProductOpener::Mail.pm module

lib/ProductOpener/Mail.pm

@@ -18,6 +18,27 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+=head1 NAME
+
+ProductOpener::Mail - sends emails to admin and producers. Moreover, replies to user queries.
+
+=head1 SYNOPSIS
+
+C<ProductOpener::Mail> is used to send emails from the contact address of the Open Food Facts to users, admin, and producers.
+
+    use ProductOpener::Mail qw/:all/;
+
+	$contact_email = 'contact@openbeautyfacts.org';
+	$admin_email = 'stephane@openfoodfacts.org';
+	$producers_email = 'producers@openfoodfacts.org';
+
+=head1 DESCRIPTION
+
+The module implements the sending of emails from the Open Food Facts contact email address to users, admin, and producers.
+These emails can be used to reply to user queries, submit feedback, or to request access from admin and producers.
+
+=cut
+
 package ProductOpener::Mail;
 
 use utf8;
@@ -44,6 +65,32 @@ use ProductOpener::Lang qw/:all/;
 use Email::Stuffer;
 use Log::Any qw($log);
 
+=head1 FUNCTIONS
+
+=head2 send_email( USER_REF, SUBJECT, TEXT )
+
+C<send_email()> sends email from the contact email of Open Food Facts to the email passed as an argument.
+
+=head3 Arguments
+
+The first argument is a hash reference. The other two arguments are scalar variables that consist of email subject and body.
+
+=head4 Input keys: user data
+
+The hash must contain values for the following keys:
+
+- email -> user email
+- name -> user name
+
+=head3 Return Values
+
+The function returns a 1 or 0 depending on the evaluation of the email sent or not.
+
+If the function catches any error during evaluation it returns 1 indicating an error.
+On the other hand, if there was no error, it returns 0 indicating that the email has been sent successfully.
+
+=cut
+
 sub send_email($$$)
 {
 	my $user_ref = shift;
@@ -68,6 +115,25 @@ sub send_email($$$)
 
 }
 
+=head1 FUNCTIONS
+
+=head2 send_email_to_admin( SUBJECT, TEXT )
+
+C<send_email_to_admin()> sends email from the contact email of Open Food Facts to the admin.
+
+=head3 Arguments
+
+Two scalar variables that contain the email subject and body are passed as an argument.
+
+=head3 Return Values
+
+The function returns a 1 or 0 depending on the evaluation of the email sent or not.
+
+If the function catches any error during evaluation it returns 1 indicating an error.
+On the other hand, if there was no error, it returns 0 indicating that the email has been sent successfully.
+
+=cut
+
 sub send_email_to_admin($$)
 {
 	my $subject = shift;
@@ -85,6 +151,25 @@ sub send_email_to_admin($$)
     return $@ ? 1 : 0;
 }
 
+=head1 FUNCTIONS
+
+=head2 send_email_to_producers_admin( SUBJECT, TEXT )
+
+C<send_email_to_producers_admin()> sends email from the contact email of Open Food Facts to producers admin.
+
+=head3 Arguments
+
+Two scalar variables that contain the email subject and body are passed as an argument.
+
+=head3 Return Values
+
+The function returns a 1 or 0 depending on the evaluation of email sent or not.
+
+If the function catches any error during evaluation it returns 1 indicating an error.
+On the other hand, if there was no error, it returns 1 indicating that email has sent successfully.
+
+=cut
+
 sub send_email_to_producers_admin($$)
 {
 	my $subject = shift;