From 002ae9419c68c45a27037d422c2553cedb3f978d Mon Sep 17 00:00:00 2001
From: Chris Boden <cboden@gmail.com>
Date: Sun, 22 Jul 2012 11:25:55 -0400
Subject: [PATCH] API documentation
---
src/Ratchet/ConnectionInterface.php | 6 +++++-
src/Ratchet/Server/IpBlackList.php | 2 ++
src/Ratchet/Wamp/WampServer.php | 12 ++++++++----
src/Ratchet/Wamp/WampServerInterface.php | 2 +-
src/Ratchet/WebSocket/HttpRequestParser.php | 7 ++++++-
src/Ratchet/WebSocket/Version/RFC6455.php | 1 +
src/Ratchet/WebSocket/VersionManager.php | 12 ++++++++++++
src/Ratchet/WebSocket/WsServer.php | 4 +++-
src/Ratchet/WebSocket/WsServerInterface.php | 3 +++
9 files changed, 41 insertions(+), 8 deletions(-)
diff --git a/src/Ratchet/ConnectionInterface.php b/src/Ratchet/ConnectionInterface.php
index a098f99..cc11fb0 100644
--- a/src/Ratchet/ConnectionInterface.php
+++ b/src/Ratchet/ConnectionInterface.php
@@ -1,11 +1,15 @@
<?php
namespace Ratchet;
+/**
+ * The version of Ratchet being used
+ * @var string
+ */
const VERSION = 'Ratchet/0.2b';
/**
* A proxy object representing a connection to the application
- * This acts as a container to storm data (in memory) about the connection
+ * This acts as a container to store data (in memory) about the connection
*/
interface ConnectionInterface {
/**
diff --git a/src/Ratchet/Server/IpBlackList.php b/src/Ratchet/Server/IpBlackList.php
index 150e560..bf41b48 100644
--- a/src/Ratchet/Server/IpBlackList.php
+++ b/src/Ratchet/Server/IpBlackList.php
@@ -19,6 +19,7 @@ class IpBlackList implements MessageComponentInterface {
}
/**
+ * Add an address to the blacklist that will not be allowed to connect to your application
* @param string IP address to block from connecting to yoru application
* @return IpBlackList
*/
@@ -29,6 +30,7 @@ class IpBlackList implements MessageComponentInterface {
}
/**
+ * Unblock an address so they can access your application again
* @param string IP address to unblock from connecting to yoru application
* @return IpBlackList
*/
diff --git a/src/Ratchet/Wamp/WampServer.php b/src/Ratchet/Wamp/WampServer.php
index 6c6c04e..48705de 100644
--- a/src/Ratchet/Wamp/WampServer.php
+++ b/src/Ratchet/Wamp/WampServer.php
@@ -5,9 +5,11 @@ use Ratchet\WebSocket\WsServerInterface;
use Ratchet\ConnectionInterface;
/**
- * This class just makes it 1 step easier to use Topic objects in WAMP
- * If you're looking at the source code, look in the __construct of this
- * class and use that to make your application instead of using this
+ * Enable support for the offical WAMP sub-protocol in your application
+ * WAMP allows for Pub/Sub and RPC
+ * @link http://wamp.ws The WAMP specification
+ * @link https://github.com/oberstet/AutobahnJS Souce for client side library
+ * @link http://autobahn.s3.amazonaws.com/js/autobahn.min.js Minified client side library
*/
class WampServer implements MessageComponentInterface, WsServerInterface {
/**
@@ -16,7 +18,9 @@ class WampServer implements MessageComponentInterface, WsServerInterface {
private $wampProtocol;
/**
- * {@inheritdoc}
+ * This class just makes it 1 step easier to use Topic objects in WAMP
+ * If you're looking at the source code, look in the __construct of this
+ * class and use that to make your application instead of using this
*/
public function __construct(WampServerInterface $app) {
$this->wampProtocol = new ServerProtocol(new TopicManager($app));
diff --git a/src/Ratchet/Wamp/WampServerInterface.php b/src/Ratchet/Wamp/WampServerInterface.php
index 3f85826..0269e06 100644
--- a/src/Ratchet/Wamp/WampServerInterface.php
+++ b/src/Ratchet/Wamp/WampServerInterface.php
@@ -4,7 +4,7 @@ use Ratchet\ComponentInterface;
use Ratchet\ConnectionInterface;
/**
- * A (not literal) extension of Ratchet\ConnectionInterface
+ * An extension of Ratchet\ComponentInterface to server a WAMP application
* onMessage is replaced by various types of messages for this protocol (pub/sub or rpc)
*/
interface WampServerInterface extends ComponentInterface {
diff --git a/src/Ratchet/WebSocket/HttpRequestParser.php b/src/Ratchet/WebSocket/HttpRequestParser.php
index f8159df..10960b1 100644
--- a/src/Ratchet/WebSocket/HttpRequestParser.php
+++ b/src/Ratchet/WebSocket/HttpRequestParser.php
@@ -6,6 +6,11 @@ use Ratchet\WebSocket\Guzzle\Http\Message\RequestFactory;
use Ratchet\WebSocket\Version\VersionInterface;
use Guzzle\Http\Message\RequestInterface;
+/**
+ * This class receives streaming data from a client request
+ * and parses HTTP headers, returning a Guzzle Request object
+ * once it's been buffered
+ */
class HttpRequestParser implements MessageInterface {
const EOM = "\r\n\r\n";
@@ -20,7 +25,7 @@ class HttpRequestParser implements MessageInterface {
* @param Ratchet\ConnectionInterface
* @param string Data stream to buffer
* @return Guzzle\Http\Message\RequestInterface|null
- * @throws OverflowException
+ * @throws OverflowException If the message buffer has become too large
*/
public function onMessage(ConnectionInterface $context, $data) {
if (!isset($context->httpBuffer)) {
diff --git a/src/Ratchet/WebSocket/Version/RFC6455.php b/src/Ratchet/WebSocket/Version/RFC6455.php
index 09af6c7..8243ed3 100644
--- a/src/Ratchet/WebSocket/Version/RFC6455.php
+++ b/src/Ratchet/WebSocket/Version/RFC6455.php
@@ -12,6 +12,7 @@ use Guzzle\Http\Message\RequestInterface;
use Guzzle\Http\Message\Response;
/**
+ * The latest version of the WebSocket protocol
* @link http://tools.ietf.org/html/rfc6455
* @todo Unicode: return mb_convert_encoding(pack("N",$u), mb_internal_encoding(), 'UCS-4BE');
*/
diff --git a/src/Ratchet/WebSocket/VersionManager.php b/src/Ratchet/WebSocket/VersionManager.php
index 942fc95..e7db28f 100644
--- a/src/Ratchet/WebSocket/VersionManager.php
+++ b/src/Ratchet/WebSocket/VersionManager.php
@@ -3,9 +3,21 @@ namespace Ratchet\WebSocket;
use Ratchet\WebSocket\Version\VersionInterface;
use Guzzle\Http\Message\RequestInterface;
+/**
+ * Manage the various versions of the WebSocket protocol
+ * This accepts interfaces of versions to enable/disable
+ */
class VersionManager {
+ /**
+ * The header string to let clients know which versions are supported
+ * @var string
+ */
private $versionString = '';
+ /**
+ * Storage of each version enabled
+ * @var array
+ */
protected $versions = array();
/**
diff --git a/src/Ratchet/WebSocket/WsServer.php b/src/Ratchet/WebSocket/WsServer.php
index 6084672..144b914 100644
--- a/src/Ratchet/WebSocket/WsServer.php
+++ b/src/Ratchet/WebSocket/WsServer.php
@@ -29,7 +29,7 @@ class WsServer implements MessageComponentInterface {
/**
* Decorated component
- * @var Ratchet\MessageComponentInterface|WsServerInterface
+ * @var Ratchet\MessageComponentInterface
*/
protected $_decorating;
@@ -46,6 +46,7 @@ class WsServer implements MessageComponentInterface {
protected $acceptedSubProtocols = array();
/**
+ * UTF-8 validator
* @var Ratchet\WebSocket\Encoding\ValidatorInterface
*/
protected $validator;
@@ -58,6 +59,7 @@ class WsServer implements MessageComponentInterface {
/**
* @param Ratchet\MessageComponentInterface Your application to run with WebSockets
+ * If you want to enable sub-protocols have your component implement WsServerInterface as well
*/
public function __construct(MessageComponentInterface $component) {
$this->reqParser = new HttpRequestParser;
diff --git a/src/Ratchet/WebSocket/WsServerInterface.php b/src/Ratchet/WebSocket/WsServerInterface.php
index 91a83cd..24c7ab9 100644
--- a/src/Ratchet/WebSocket/WsServerInterface.php
+++ b/src/Ratchet/WebSocket/WsServerInterface.php
@@ -1,6 +1,9 @@
<?php
namespace Ratchet\WebSocket;
+/**
+ * WebSocket Server Interface
+ */
interface WsServerInterface {
/**
* If any component in a stack supports a WebSocket sub-protocol return each supported in an array