add docs for the mail class

Signed-off-by: Dieter Coopman <dieter@deltasolutions.be>

Author: dietercoopman

src/Mail.php

@@ -6,15 +6,39 @@
 use LLoadout\Microsoftgraph\Traits\Authenticate;
 use LLoadout\Microsoftgraph\Traits\Connect;
 
+/**
+ * Mail class for interacting with Microsoft Graph API's mail functionality
+ *
+ * This class provides methods to interact with Microsoft Graph API's mail features including:
+ * - Sending emails with attachments
+ * - Managing mail folders
+ * - Reading and managing messages
+ * - Moving messages between folders
+ * - Retrieving message attachments
+ *
+ * @package LLoadout\Microsoftgraph
+ */
 class Mail
 {
     use Authenticate, Connect;
 
+    /**
+     * Send an email using Microsoft Graph API
+     *
+     * @param mixed $mailable The mailable object containing email details
+     * @return void
+     */
     public function sendMail($mailable): void
     {
         $this->post('/me/sendMail', $this->getBody($mailable));
     }
 
+    /**
+     * Prepare the email body for sending
+     *
+     * @param mixed $mailable The mailable object
+     * @return array The formatted email body
+     */
     protected function getBody($mailable)
     {
         $html = $mailable->getHtmlBody();
@@ -40,6 +64,12 @@ protected function getBody($mailable)
         ]);
     }
 
+    /**
+     * Format email recipients into Microsoft Graph API format
+     *
+     * @param mixed $recipients Single recipient or array of recipients
+     * @return array Formatted recipients array
+     */
     protected function formatRecipients($recipients): array
     {
         $addresses = [];
@@ -64,6 +94,12 @@ protected function formatRecipients($recipients): array
         return $addresses;
     }
 
+    /**
+     * Format email content into Microsoft Graph API format
+     *
+     * @param string $html HTML content of the email
+     * @return array Formatted content array
+     */
     private function getContent($html): array
     {
         return [
@@ -72,6 +108,12 @@ private function getContent($html): array
         ];
     }
 
+    /**
+     * Convert attachments into Microsoft Graph API format
+     *
+     * @param array $attachments Array of attachment files
+     * @return array Formatted attachments array
+     */
     protected function toAttachmentCollection($attachments): array
     {
         $collection = [];
@@ -97,23 +139,43 @@ protected function toAttachmentCollection($attachments): array
         return $collection;
     }
 
+    /**
+     * Get all mail folders for the authenticated user
+     *
+     * @return array Mail folders
+     */
     public function getMailFolders()
     {
         $url ='/me/mailfolders';
 
         return $this->get($url);
     }
 
+    /**
+     * Get subfolders for a specific mail folder
+     *
+     * @param string $id Parent folder ID
+     * @return array Subfolders
+     */
     public function getSubFolders($id)
     {
         $url = '/me/mailfolders/' . $id . '/childFolders';
 
         return $this->get($url);
     }
 
+    /**
+     * Get messages from a specific mail folder
+     *
+     * @param string $folder Folder name (default: 'inbox')
+     * @param bool $isRead Include read messages (default: true)
+     * @param int $skip Number of messages to skip (default: 0)
+     * @param int $limit Maximum number of messages to return (default: 20)
+     * @return array Messages
+     */
     public function getMailMessagesFromFolder($folder = 'inbox', $isRead = true, $skip = 0, $limit = 20)
     {
-        $url = '/me/mailfolders/' . $folder . '/messages?$select=Id,ReceivedDateTime,Subject,Sender,ToRecipients,From,HasAttachments,InternetMessageHeaders&$skip='.$skip.'&$top='.$limit;
+        $url = '/me/mailfolders/' . $folder . '/messages?$select=Id,ReceivedDateTime,Subject,Sender,ToRecipients,From,Body,HasAttachments,InternetMessageHeaders&$skip='.$skip.'&$top='.$limit;
         if (! $isRead) {
             $url .= '&$filter=isRead ne true';
         }
@@ -131,33 +193,60 @@ public function getMailMessagesFromFolder($folder = 'inbox', $isRead = true, $sk
                 'from'         => $mail['from']['emailAddress'],
                 'to'           => ! blank($to) ? $to : optional($mail['toRecipients'])[0]['emailAddress']['address'],
                 'attachements' => $mail['hasAttachments'],
+                'body'         => $mail['body']['content'],
             ];
         }
 
         return $mails;
     }
 
+    /**
+     * Update a message
+     *
+     * @param string $id Message ID
+     * @param array $data Update data
+     * @return mixed API response
+     */
     public function updateMessage($id, $data)
     {
         $url = '/me/messages/' . $id;
 
         return $this->patch($url, $data);
     }
 
+    /**
+     * Move a message to a different folder
+     *
+     * @param string $id Message ID
+     * @param string $destinationId Destination folder ID
+     * @return mixed API response
+     */
     public function moveMessage($id, $destinationId)
     {
         $url = '/me/messages/' . $id . '/move';
 
         return $this->post($url, ['destinationId' => $destinationId]);
     }
 
+    /**
+     * Get a specific message by ID
+     *
+     * @param string $id Message ID
+     * @return mixed Message details
+     */
     public function getMessage($id)
     {
         $url = config('socialite.office365.api_url') . '/me/messages/' . $id . '?$select=Id,ReceivedDateTime,createdDateTime,Subject,Sender,ToRecipients,From,HasAttachments,InternetMessageHeaders&$top=10&$skip=0';
 
         return $this->get($url);
     }
 
+    /**
+     * Get attachments for a specific message
+     *
+     * @param string $id Message ID
+     * @return mixed Message attachments
+     */
     public function getMessageAttachements($id)
     {
         $url = '/me/messages/' . $id . '/attachments';