From 39821585e4ecfa21345bd87366c10b28a3a93673 Mon Sep 17 00:00:00 2001
From: netkas <netkas@n64.cc>
Date: Fri, 1 Nov 2024 21:25:50 -0400
Subject: [PATCH] Add detailed docblocks to PollingBot class methods

---
 src/TgBotLib/PollingBot.php | 54 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 53 insertions(+), 1 deletion(-)

diff --git a/src/TgBotLib/PollingBot.php b/src/TgBotLib/PollingBot.php
index a3b6c42..cadfa9d 100644
--- a/src/TgBotLib/PollingBot.php
+++ b/src/TgBotLib/PollingBot.php
@@ -5,8 +5,10 @@
     use TgBotLib\Abstracts\UpdateEvent;
     use TgBotLib\Classes\Utilities;
     use TgBotLib\Enums\UpdateEventType;
-    use TgBotLib\Objects\Update;
 
+    /**
+     * PollingBot class that extends Bot for handling updates using polling.
+     */
     class PollingBot extends Bot
     {
         private ?int $offset;
@@ -34,31 +36,65 @@
             $this->offset = $offset;
         }
 
+        /**
+         * Retrieves the current offset value.
+         *
+         * @return int The current offset.
+         */
         public function getOffset(): int
         {
             return $this->offset;
         }
 
+        /**
+         * Sets the limit for the number of items to process.
+         *
+         * @param int $limit The maximum number of items to be processed.
+         * @return void
+         */
         public function setLimit(int $limit): void
         {
             $this->limit = $limit;
         }
 
+        /**
+         * Retrieves the limit for the current operation.
+         *
+         * @return int The limit value.
+         */
         public function getLimit(): int
         {
             return $this->limit;
         }
 
+        /**
+         * Sets the timeout value.
+         *
+         * @param int $timeout The timeout value to set.
+         * @return void
+         */
         public function setTimeout(int $timeout): void
         {
             $this->timeout = $timeout;
         }
 
+        /**
+         * Retrieves the current timeout setting.
+         *
+         * @return int The configured timeout value.
+         */
         public function getTimeout(): int
         {
             return $this->timeout;
         }
 
+        /**
+         * Sets the list of allowed updates.
+         *
+         * @param array $allowedUpdates The array of update types that should be allowed.
+         *
+         * @return void
+         */
         public function setAllowedUpdates(array $allowedUpdates): void
         {
             $this->allowedUpdates = $allowedUpdates;
@@ -69,6 +105,12 @@
             return $this->allowedUpdates;
         }
 
+        /**
+         * Adds a new allowed update type to the list if it does not already exist.
+         *
+         * @param string $allowedUpdate The type of update to allow.
+         * @return void
+         */
         public function addAllowedUpdate(string $allowedUpdate): void
         {
             if(in_array($allowedUpdate, $this->allowedUpdates))
@@ -79,6 +121,11 @@
             $this->allowedUpdates[] = $allowedUpdate;
         }
 
+        /**
+         * Handles incoming updates by fetching and processing them with appropriate event handlers.
+         *
+         * @return void
+         */
         public function handleUpdates(): void
         {
             foreach($this->getUpdates(offset: ($this->offset ?: 0), limit: $this->limit, timeout: $this->timeout, allowed_updates: $this->retrieveAllowedUpdates()) as $update)
@@ -113,6 +160,11 @@
             }
         }
 
+        /**
+         * Retrieves the allowed updates.
+         *
+         * @return array|null Returns an array of allowed updates if available, otherwise null.
+         */
         private function retrieveAllowedUpdates(): ?array
         {
             if(count($this->allowedUpdates) === 0)