Merge pull request #55 from clue-labs/docs

Improve README and API documentation

Author: clue

README.md

@@ -2,12 +2,19 @@
 
 namespace Clue\React\Ami;
 
-use Clue\React\Ami\Client;
 use Clue\React\Ami\Protocol\Collection;
 use Clue\React\Ami\Protocol\Event;
 use Clue\React\Ami\Protocol\Response;
 use React\Promise\Deferred;
 
+/**
+ * The `ActionSender` wraps a given [`Client`](#client) instance to provide a simple way to execute common actions.
+ * This class represents the main interface to execute actions and wait for the corresponding responses.
+ *
+ * ```php
+ * $sender = new Clue\React\Ami\ActionSender($client);
+ * ```
+ */
 class ActionSender
 {
     private $client;
@@ -17,33 +24,64 @@ public function __construct(Client $client)
         $this->client = $client;
     }
 
+    /**
+     * @param string $username
+     * @param string $secret
+     * @param ?bool  $events
+     * @return \React\Promise\PromiseInterface<Response,\Exception>
+     * @link https://wiki.asterisk.org/wiki/display/AST/Asterisk+14+ManagerAction_Login
+     */
     public function login($username, $secret, $events = null)
     {
         $events = $this->boolParam($events);
         return $this->request('Login', array('UserName' => $username, 'Secret' => $secret, 'Events' => $events));
     }
 
+    /**
+     * @return \React\Promise\PromiseInterface<Response,\Exception>
+     * @link https://wiki.asterisk.org/wiki/display/AST/Asterisk+14+ManagerAction_Logoff
+     */
     public function logoff()
     {
         return $this->request('Logoff');
     }
 
+    /**
+     * @param string $agentId
+     * @param bool   $soft
+     * @return \React\Promise\PromiseInterface<Response,\Exception>
+     * @link https://wiki.asterisk.org/wiki/display/AST/Asterisk+14+ManagerAction_AgentLogoff
+     */
     public function agentLogoff($agentId, $soft = false)
     {
         $bool = $soft ? 'true' : 'false';
         return $this->request('AgentLogoff', array('Agent' => $agentId, 'Soft' => $bool));
     }
 
+    /**
+     * @return \React\Promise\PromiseInterface<Response,\Exception>
+     * @link https://wiki.asterisk.org/wiki/display/AST/Asterisk+14+ManagerAction_Ping
+     */
     public function ping()
     {
         return $this->request('Ping');
     }
 
+    /**
+     * @param string $command
+     * @return \React\Promise\PromiseInterface<Response,\Exception>
+     * @link https://wiki.asterisk.org/wiki/display/AST/Asterisk+14+ManagerAction_Command
+     */
     public function command($command)
     {
         return $this->request('Command', array('Command' => $command));
     }
 
+    /**
+     * @param bool|string[] $eventMask
+     * @return \React\Promise\PromiseInterface<Response,\Exception>
+     * @link https://wiki.asterisk.org/wiki/display/AST/Asterisk+14+ManagerAction_Events
+     */
     public function events($eventMask)
     {
         if ($eventMask === false) {
@@ -57,62 +95,99 @@ public function events($eventMask)
         return $this->request('Events', array('EventMask' => $eventMask));
     }
 
+    /**
+     * @param string $peerName
+     * @return \React\Promise\PromiseInterface<Response,\Exception>
+     * @link https://wiki.asterisk.org/wiki/display/AST/Asterisk+14+ManagerAction_SIPshowpeer
+     */
     public function sipShowPeer($peerName)
     {
         return $this->request('SIPshowpeer', array('Peer' => $peerName));
     }
 
+    /**
+     * @return \React\Promise\PromiseInterface<Response,\Exception>
+     * @link https://wiki.asterisk.org/wiki/display/AST/Asterisk+14+ManagerAction_ListCommands
+     */
     public function listCommands()
     {
         return $this->request('ListCommands');
     }
 
+    /**
+     * @param string $channel
+     * @param string $message
+     * @return \React\Promise\PromiseInterface<Response,\Exception>
+     * @link https://wiki.asterisk.org/wiki/display/AST/Asterisk+14+ManagerAction_SendText
+     */
     public function sendText($channel, $message)
     {
         return $this->request('Sendtext', array('Channel' => $channel, 'Message' => $message));
     }
 
+    /**
+     * @param string $channel
+     * @param int $cause
+     * @return \React\Promise\PromiseInterface<Response,\Exception>
+     * @link https://wiki.asterisk.org/wiki/display/AST/Asterisk+14+ManagerAction_Hangup
+     */
     public function hangup($channel, $cause)
     {
         return $this->request('Hangup', array('Channel' => $channel, 'Cause' => $cause));
     }
 
+    /**
+     * @param string $authType
+     * @return \React\Promise\PromiseInterface<Response,\Exception>
+     * @link https://wiki.asterisk.org/wiki/display/AST/Asterisk+14+ManagerAction_Challenge
+     */
     public function challenge($authType = 'MD5')
     {
         return $this->request('Challenge', array('AuthType' => $authType));
     }
 
+    /**
+     * @param string  $filename
+     * @param ?string $category
+     * @return \React\Promise\PromiseInterface<Response,\Exception>
+     * @link https://wiki.asterisk.org/wiki/display/AST/Asterisk+14+ManagerAction_GetConfig
+     */
     public function getConfig($filename, $category = null)
     {
         return $this->request('GetConfig', array('Filename' => $filename, 'Category' => $category));
     }
 
     /**
-     * @return \React\Promise\PromiseInterface Promise<Collection> collection with "Event: CoreShowChannel"
+     * @return \React\Promise\PromiseInterface<Collection,\Exception> collection with "Event: CoreShowChannel"
+     * @link https://wiki.asterisk.org/wiki/display/AST/Asterisk+14+ManagerAction_CoreShowChannels
      */
     public function coreShowChannels()
     {
         return $this->collectEvents('CoreShowChannels', 'CoreShowChannelsComplete');
     }
 
     /**
-     *
-     * @return \React\Promise\PromiseInterface Promise<Collection> collection with "Event: PeerEntry"
+     * @return \React\Promise\PromiseInterface<Collection,\Exception> collection with "Event: PeerEntry"
+     * @link https://wiki.asterisk.org/wiki/display/AST/Asterisk+14+ManagerAction_SIPpeers
      */
     public function sipPeers()
     {
         return $this->collectEvents('SIPPeers', 'PeerlistComplete');
     }
 
     /**
-     *
-     * @return \React\Promise\PromiseInterface Promise<Collection> collection with "Event: Agents"
+     * @return \React\Promise\PromiseInterface<Collection,\Exception>collection with "Event: Agents"
+     * @link https://wiki.asterisk.org/wiki/display/AST/Asterisk+14+ManagerAction_Agents
      */
     public function agents()
     {
         return $this->collectEvents('Agents', 'AgentsComplete');
     }
 
+    /**
+     * @param mixed $value
+     * @return ?string
+     */
     private function boolParam($value)
     {
         if ($value === true) {
@@ -124,11 +199,21 @@ private function boolParam($value)
         return null;
     }
 
+    /**
+     * @param string $name
+     * @param array $args
+     * @return \React\Promise\PromiseInterface<Response,\Exception>
+     */
     private function request($name, array $args = array())
     {
         return $this->client->request($this->client->createAction($name, $args));
     }
 
+    /**
+     * @param string $command
+     * @param string $expectedEndEvent
+     * @return \React\Promise\PromiseInterface<Collection,\Exception>
+     */
     private function collectEvents($command, $expectedEndEvent)
     {
         $req = $this->client->createAction($command);

src/ActionSender.php

@@ -14,6 +14,15 @@
 use Exception;
 use UnexpectedValueException;
 
+/**
+ * The `Client` is responsible for exchanging messages with the Asterisk Manager Interface
+ * and keeps track of pending actions.
+ *
+ * If you want to send outgoing actions, see below for the [`ActionSender`](#actionsender) class.
+ *
+ * Besides defining a few methods, this interface also implements the
+ * `EventEmitterInterface` which allows you to react to certain events as documented below.
+ */
 class Client extends EventEmitter
 {
     private $stream;
@@ -49,6 +58,27 @@ public function __construct(ConnectionInterface $stream, Parser $parser = null)
         $this->stream->on('close', array ($that, 'close'));
     }
 
+    /**
+     * Queue the given messages to be sent via AMI
+     * and wait for a [`Response`](#response) object that matches the value of its "ActionID" field.
+     *
+     * This method is considered advanced usage and mostly used internally only.
+     * Creating [`Action`](#action) objects, sending them via AMI and waiting
+     * for incoming [`Response`](#response) objects is usually hidden behind the
+     * [`ActionSender`](#actionsender) interface.
+     *
+     * If you happen to need a custom or otherwise unsupported action, you can
+     * also do so manually as follows. Consider filing a PR to add new actions
+     * to the [`ActionSender`](#actionsender).
+     *
+     * ```php
+     * $action = $client->createAction('Originate', array('Channel' => …));
+     * $promise = $client->request($action);
+     * ```
+     *
+     * @param Action $message
+     * @return \React\Promise\PromiseInterface<Response,\Exception>
+     */
     public function request(Action $message)
     {
         $deferred = new Deferred();
@@ -91,6 +121,11 @@ public function handleMessage(Message $message)
         }
     }
 
+    /**
+     * Force-close the AMI connection and reject all pending actions.
+     *
+     * @return void
+     */
     public function close()
     {
         if ($this->stream === null) {
@@ -112,6 +147,11 @@ public function close()
         $this->pending = array();
     }
 
+    /**
+     * Soft-close the AMI connection once all pending actions are completed.
+     *
+     * @return void
+     */
     public function end()
     {
         $this->ending = true;
@@ -126,6 +166,30 @@ public function isBusy()
         return !!$this->pending;
     }
 
+    /**
+     * Construct a custom AMI action.
+     *
+     * This method is considered advanced usage and mostly used internally only.
+     * Creating [`Action`](#action) objects, sending them via AMI and waiting
+     * for incoming [`Response`](#response) objects is usually hidden behind the
+     * [`ActionSender`](#actionsender) interface.
+     *
+     * If you happen to need a custom or otherwise unsupported action, you can
+     * also do so manually as follows. Consider filing a PR to add new actions
+     * to the [`ActionSender`](#actionsender).
+     *
+     * A unique value will be added to "ActionID" field automatically (needed to
+     * match the incoming responses).
+     *
+     * ```php
+     * $action = $client->createAction('Originate', array('Channel' => …));
+     * $promise = $client->request($action);
+     * ```
+     *
+     * @param string $name
+     * @param array $args
+     * @return Action
+     */
     public function createAction($name, array $args = array())
     {
         $args = array('Action' => $name, 'ActionID' => (string)++$this->actionId) + $args;