Improved quality of docblock comments

examples/semaphores.php

@@ -0,0 +1,21 @@
+<?php
+
+require_once __DIR__."/../vendor/autoload.php";
+
+use NoccyLabs\Ipc\Key\FileKey;
+use NoccyLabs\Ipc\Sem\Semaphore;
+
+$key = new FileKey(__FILE__);
+
+// Create semaphore with max count of 2
+$sem1 = new Semaphore($key, 2); 
+$sem2 = new Semaphore($key, 2); 
+$sem3 = new Semaphore($key, 2); 
+
+printf("sem1 acquire: %d\n", $sem1->acquire());
+printf("sem2 acquire: %d\n", $sem2->acquire());
+printf("sem3 acquire: %d\n", $sem3->acquire());
+printf("sem2 release: %d\n", $sem2->release());
+printf("sem3 acquire: %d\n", $sem3->acquire());
+
+$sem1->destroy();

src/Interop/Channel/ChannelInterface.php

@@ -5,9 +5,25 @@ namespace NoccyLabs\Ipc\Interop\Channel;
 
 interface ChannelInterface
 {
+    /**
+     * Check if the channel is open
+     *
+     * @return boolean
+     */
     public function isOpen():bool;
 
+    /**
+     * Receive (and unserialize) a frame of data.
+     *
+     * @return mixed
+     */
     public function receive();
 
+    /**
+     * Send a frame of data
+     *
+     * @param mixed $data
+     * @return void
+     */
     public function send($data);
 }

src/Interop/Channel/StreamChannel.php

@@ -2,11 +2,19 @@
 
 namespace NoccyLabs\Ipc\Interop\Channel;
 
-
+/**
+ * Channel based on streams
+ * 
+ */
 class StreamChannel implements ChannelInterface
 {
     protected $stream;
 
+    /**
+     * Constructor
+     *
+     * @param resource|string $stream
+     */
     public function __construct($stream)
     {
         if (!is_resource($stream)) {
@@ -20,15 +28,24 @@ class StreamChannel implements ChannelInterface
         }
         
         $this->stream = $stream;
-
-        $this->isOpen();
     }
     
+    /**
+     * {@inheritDoc}
+     *
+     * @param mixed $data
+     * @return void
+     */
     public function send($data)
     {
         fwrite($this->stream, json_encode($data)."\0");
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @return mixed
+     */
     public function receive()
     {
         $buf = fread($this->stream, 8192);
@@ -36,11 +53,21 @@ class StreamChannel implements ChannelInterface
         return json_decode(rtrim($buf, "\0"));
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @return boolean
+     */
     public function isOpen(): bool
     {
         return is_resource($this->stream);
     }
 
+    /**
+     * Create a pair of connected StreamChannel instances
+     *
+     * @return StreamChannel[]
+     */
     public static function createPair()
     {
         $fd = stream_socket_pair(STREAM_PF_UNIX, STREAM_SOCK_STREAM, STREAM_IPPROTO_IP);

src/Key/KeyInterface.php

@@ -4,6 +4,10 @@ namespace NoccyLabs\Ipc\Key;
 
 interface KeyInterface
 {
+    /**
+     * Get the integer key used for SysV ipc operations
+     *
+     * @return integer
+     */
     public function getKey():int;
-    public function __toString();
 }

src/Msg/Queue.php

@@ -32,6 +32,11 @@ class Queue
 
     }
 
+    /**
+     * Destroy the queue
+     *
+     * @return void
+     */
     public function destroy()
     {
         if ($this->resource) {

src/Sem/Semaphore.php

@@ -20,9 +20,9 @@ class Semaphore
         sem_remove($this->resource);
     }
 
-    public function acquire(float $timeout = 0):bool
+    public function acquire(bool $wait = false):bool
     {
-        return sem_acquire($this->resource, true);
+        return sem_acquire($this->resource, !$wait);
     }
 
     public function release():bool

src/Signal/Signal.php

@@ -7,17 +7,34 @@ class Signal
 {
     private $signo;
 
+    /**
+     * Constructor
+     *
+     * @param integer $signo
+     */
     public function __construct(int $signo)
     {
         $this->signo = $signo;
     }
 
+    /**
+     * Set a signal handler, overwriting any previous handler
+     *
+     * @param callable $handler
+     * @return void
+     */
     public function setHandler(callable $handler):void
     {
         pcntl_signal($this->signo, $handler);
     }
 
-    public function dispatch($pid=null):bool
+    /**
+     * Dispatch the signal to the specified pid. Default is own pid
+     *
+     * @param int $pid
+     * @return boolean
+     */ 
+    public function dispatch(int $pid=null):bool
     {
         return posix_kill($pid?:posix_getpid(), $this->signo);
     }

src/Signal/SignalHandler.php

@@ -9,6 +9,13 @@ class SignalHandler
 
     private $callbacks;
 
+    /**
+     * Constructor, should only be called once for each signal but can have
+     * multiple handlers attached.
+     *
+     * @param integer $signo
+     * @param array $callbacks
+     */
     public function __construct(int $signo, array $callbacks=[])
     {
         $this->signo = $signo;
@@ -21,11 +28,23 @@ class SignalHandler
 
     }
 
+    /**
+     * Append a handler to the signal
+     *
+     * @param callable $handler
+     * @return void
+     */
     public function addHandler(callable $handler):void
     {
         $this->callbacks[] = $handler;
     }
 
+    /**
+     * Callback for signals
+     *
+     * @param int $signo
+     * @return void
+     */
     public function onSignal($signo)
     {
         foreach ($this->callbacks as $callback) {

src/Signal/SignalTrap.php

@@ -9,17 +9,33 @@ class SignalTrap
 
     protected $trapped = false;
 
+    /**
+     * Constructor
+     *
+     * @param integer $signo
+     */
     public function __construct(int $signo)
     {
         $this->signal = new Signal($signo);
         $this->signal->setHandler([ $this, "onSignal" ]);
     }
 
+    /**
+     * Signal handler callback
+     *
+     * @return void
+     */
     public function onSignal()
     {
         $this->trapped = true;
     }
 
+    /**
+     * Check if the signal has been received
+     *
+     * @param boolean $reset
+     * @return boolean
+     */
     public function isTrapped($reset=true):bool
     {
         if ($this->trapped) {