doc strings added

Author: ArnabChatterjee20k

src/Pools/Adapter/Stack.php

@@ -24,8 +24,13 @@ public function push(mixed $connection): static
     }
 
     /**
-     * @param int $timeout Stack adapter will ignore timeout
-     * @return mixed
+     * Pop an item from the stack.
+     *
+     * Note: The stack adapter does not support blocking operations.
+     * The `$timeout` parameter is ignored.
+     *
+     * @param int $timeout Ignored by the stack adapter.
+     * @return mixed|null Returns the popped item, or null if the stack is empty.
      */
     public function pop(int $timeout): mixed
     {
@@ -38,10 +43,14 @@ public function count(): int
     }
 
     /**
-     * No lock applied and just the callback is executed
-     * @param callable $callback
-     * @param int $timeout
-     * @return mixed
+     * Executes the callback without acquiring a lock.
+     *
+     * This implementation does not provide mutual exclusion.
+     * The `$timeout` parameter is ignored.
+     *
+     * @param callable $callback Callback to execute.
+     * @param int $timeout Ignored.
+     * @return mixed The value returned by the callback.
      */
     public function withLock(callable $callback, int $timeout): mixed
     {

src/Pools/Adapter/Swoole.php

@@ -30,30 +30,38 @@ public function push(mixed $connection): static
         return $this;
     }
 
+    /**
+     * Pop an item from the pool.
+     *
+     * @param int $timeout Timeout in seconds. Use 0 for non-blocking pop.
+     * @return mixed|false Returns the pooled value, or false if the pool is empty
+     *                     or the timeout expires.
+     */
     public function pop(int $timeout): mixed
     {
-        $result = $this->pool->pop($timeout);
-
-        // if pool is empty or timeout occured => result will be false
-        return $result;
+        return $this->pool->pop($timeout);
     }
 
-
     public function count(): int
     {
         $length = $this->pool->length();
         return is_int($length) ? $length : 0;
     }
 
     /**
-     * Executes the callback under a lock and releases it afterward.
-     * @param callable $callback
-     * @param int $timeout
-     * @return mixed
-     */
+     * Executes a callback while holding a lock.
+     *
+     * The lock is acquired before invoking the callback and is always released
+     * afterward, even if the callback throws an exception.
+     *
+     * @param callable $callback Callback to execute within the critical section.
+     * @param int $timeout Maximum time (in seconds) to wait for the lock.
+     * @return mixed The value returned by the callback.
+     *
+     * @throws \RuntimeException If the lock cannot be acquired within the timeout.
+    */
     public function withLock(callable $callback, int $timeout): mixed
     {
-        // Acquire lock for thread-safe operations with timeout to prevent deadlock
         $acquired = $this->lock->lockwait($timeout);
 
         if (!$acquired) {