From f905e3ad1f4e8a4092fee5b85fd54186539ce60f Mon Sep 17 00:00:00 2001 From: Chris Boden Date: Sat, 5 Jan 2013 16:10:21 -0500 Subject: [PATCH] OCD API documentation updates --- Encoding/Validator.php | 4 ++-- Encoding/ValidatorInterface.php | 4 ++-- HttpRequestParser.php | 10 ++++----- Version/Hixie76.php | 4 ++-- Version/MessageInterface.php | 2 +- Version/RFC6455.php | 16 ++++++++------ Version/RFC6455/Frame.php | 31 ++++++++++++++++----------- Version/RFC6455/HandshakeVerifier.php | 6 +++--- Version/RFC6455/Message.php | 2 +- Version/VersionInterface.php | 16 +++++++------- VersionManager.php | 15 +++++++------ WsServer.php | 17 ++++++++------- 12 files changed, 70 insertions(+), 57 deletions(-) diff --git a/Encoding/Validator.php b/Encoding/Validator.php index b0d59a4..0dc8a24 100644 --- a/Encoding/Validator.php +++ b/Encoding/Validator.php @@ -49,8 +49,8 @@ class Validator { } /** - * @param string The value to check the encoding - * @param string The type of encoding to check against + * @param string $str The value to check the encoding + * @param string $against The type of encoding to check against * @return bool */ public function checkEncoding($str, $against) { diff --git a/Encoding/ValidatorInterface.php b/Encoding/ValidatorInterface.php index 2231c05..c5769e8 100644 --- a/Encoding/ValidatorInterface.php +++ b/Encoding/ValidatorInterface.php @@ -4,8 +4,8 @@ namespace Ratchet\WebSocket\Encoding; interface ValidatorInterface { /** * Verify a string matches the encoding type - * @param string The string to check - * @param string The encoding type to check against + * @param string $str The string to check + * @param string $encoding The encoding type to check against * @return bool */ function checkEncoding($str, $encoding); diff --git a/HttpRequestParser.php b/HttpRequestParser.php index e031928..e7ee10f 100644 --- a/HttpRequestParser.php +++ b/HttpRequestParser.php @@ -20,10 +20,10 @@ class HttpRequestParser implements MessageInterface { public $maxSize = 4096; /** - * @param Ratchet\ConnectionInterface - * @param string Data stream to buffer - * @return Guzzle\Http\Message\RequestInterface|null - * @throws OverflowException If the message buffer has become too large + * @param \Ratchet\ConnectionInterface $context + * @param string $data Data stream to buffer + * @return \Guzzle\Http\Message\RequestInterface|null + * @throws \OverflowException If the message buffer has become too large */ public function onMessage(ConnectionInterface $context, $data) { if (!isset($context->httpBuffer)) { @@ -47,7 +47,7 @@ class HttpRequestParser implements MessageInterface { /** * Determine if the message has been buffered as per the HTTP specification - * @param string + * @param string $message * @return boolean */ public function isEom($message) { diff --git a/Version/Hixie76.php b/Version/Hixie76.php index 0e15153..fbb8e1d 100644 --- a/Version/Hixie76.php +++ b/Version/Hixie76.php @@ -34,8 +34,8 @@ class Hixie76 implements VersionInterface { } /** - * @param Guzzle\Http\Message\RequestInterface - * @return Guzzle\Http\Message\Response + * @param \Guzzle\Http\Message\RequestInterface $request + * @return \Guzzle\Http\Message\Response */ public function handshake(RequestInterface $request) { $body = $this->sign($request->getHeader('Sec-WebSocket-Key1', true), $request->getHeader('Sec-WebSocket-Key2', true), (string)$request->getBody()); diff --git a/Version/MessageInterface.php b/Version/MessageInterface.php index dc126d6..ff29163 100644 --- a/Version/MessageInterface.php +++ b/Version/MessageInterface.php @@ -3,7 +3,7 @@ namespace Ratchet\WebSocket\Version; interface MessageInterface extends DataInterface { /** - * @param FragmentInterface + * @param FrameInterface $fragment * @return MessageInterface */ function addFrame(FrameInterface $fragment); diff --git a/Version/RFC6455.php b/Version/RFC6455.php index d87f19e..94416c3 100644 --- a/Version/RFC6455.php +++ b/Version/RFC6455.php @@ -31,7 +31,7 @@ class RFC6455 implements VersionInterface { private $closeCodes = array(); /** - * @var Ratchet\WebSocket\Encoding\ValidatorInterface + * @var \Ratchet\WebSocket\Encoding\ValidatorInterface */ protected $validator; @@ -78,8 +78,9 @@ class RFC6455 implements VersionInterface { } /** - * @param Ratchet\ConnectionInterface - * @return Ratchet\WebSocket\Version\RFC6455\Connection + * @param \Ratchet\ConnectionInterface $conn + * @param \Ratchet\MessageInterface $coalescedCallback + * @return \Ratchet\WebSocket\Version\RFC6455\Connection */ public function upgradeConnection(ConnectionInterface $conn, MessageInterface $coalescedCallback) { $upgraded = new Connection($conn); @@ -94,8 +95,8 @@ class RFC6455 implements VersionInterface { } /** - * @param Ratchet\WebSocket\Version\RFC6455\Connection - * @param string + * @param \Ratchet\WebSocket\Version\RFC6455\Connection $from + * @param string $data */ public function onMessage(ConnectionInterface $from, $data) { $overflow = ''; @@ -214,6 +215,9 @@ class RFC6455 implements VersionInterface { } /** + * @param string|null $payload + * @param bool|null $final + * @param int|null $opcode * @return RFC6455\Frame */ public function newFrame($payload = null, $final = null, $opcode = null) { @@ -222,7 +226,7 @@ class RFC6455 implements VersionInterface { /** * Used when doing the handshake to encode the key, verifying client/server are speaking the same language - * @param string + * @param string $key * @return string * @internal */ diff --git a/Version/RFC6455/Frame.php b/Version/RFC6455/Frame.php index 9d6c8f5..146bd06 100644 --- a/Version/RFC6455/Frame.php +++ b/Version/RFC6455/Frame.php @@ -62,6 +62,12 @@ class Frame implements FrameInterface { */ protected $secondByte = -1; + + /** + * @param string|null $payload + * @param bool $final + * @param int $opcode + */ public function __construct($payload = null, $final = true, $opcode = 1) { if (null === $payload) { return; @@ -136,7 +142,7 @@ class Frame implements FrameInterface { /** * @return boolean - * @throws UnderflowException + * @throws \UnderflowException */ public function getRsv1() { if (-1 === $this->firstByte) { @@ -148,7 +154,7 @@ class Frame implements FrameInterface { /** * @return boolean - * @throws UnderflowException + * @throws \UnderflowException */ public function getRsv2() { if (-1 === $this->firstByte) { @@ -160,7 +166,7 @@ class Frame implements FrameInterface { /** * @return boolean - * @throws UnderflowException + * @throws \UnderflowException */ public function getRsv3() { if (-1 === $this->firstByte) { @@ -215,8 +221,9 @@ class Frame implements FrameInterface { /** * Apply a mask to the payload * @param string|null If NULL is passed a masking key will be generated - * @throws InvalidArgumentException If there is an issue with the given masking key - * @throws UnderflowException If the frame is not coalesced + * @throws \OutOfBoundsException + * @throws \InvalidArgumentException If there is an issue with the given masking key + * @return Frame */ public function maskPayload($maskingKey = null) { if (null === $maskingKey) { @@ -246,7 +253,7 @@ class Frame implements FrameInterface { /** * Remove a mask from the payload - * @throws UnderFlowException If the frame is not coalesced + * @throws \UnderFlowException If the frame is not coalesced * @return Frame */ public function unMaskPayload() { @@ -273,10 +280,10 @@ class Frame implements FrameInterface { /** * Apply a mask to a string or the payload of the instance - * @param string The 4 character masking key to be applied - * @param string|null A string to mask or null to use the payload - * @throws UnderflowException If using the payload but enough hasn't been buffered - * @return string The masked string + * @param string $maskingKey The 4 character masking key to be applied + * @param string|null $payload A string to mask or null to use the payload + * @throws \UnderflowException If using the payload but enough hasn't been buffered + * @return string The masked string */ public function applyMask($maskingKey, $payload = null) { if (null === $payload) { @@ -309,7 +316,7 @@ class Frame implements FrameInterface { /** * Gets the decimal value of bits 9 (10th) through 15 inclusive * @return int - * @throws UnderflowException If the buffer doesn't have enough data to determine this + * @throws \UnderflowException If the buffer doesn't have enough data to determine this */ protected function getFirstPayloadVal() { if (-1 === $this->secondByte) { @@ -321,7 +328,7 @@ class Frame implements FrameInterface { /** * @return int (7|23|71) Number of bits defined for the payload length in the fame - * @throws UnderflowException + * @throws \UnderflowException */ protected function getNumPayloadBits() { if (-1 === $this->secondByte) { diff --git a/Version/RFC6455/HandshakeVerifier.php b/Version/RFC6455/HandshakeVerifier.php index c86dbef..7fbf452 100644 --- a/Version/RFC6455/HandshakeVerifier.php +++ b/Version/RFC6455/HandshakeVerifier.php @@ -10,7 +10,7 @@ use Guzzle\Http\Message\RequestInterface; class HandshakeVerifier { /** * Given an array of the headers this method will run through all verification methods - * @param Guzzle\Http\Message\RequestInterface + * @param \Guzzle\Http\Message\RequestInterface $request * @return bool TRUE if all headers are valid, FALSE if 1 or more were invalid */ public function verifyAll(RequestInterface $request) { @@ -78,7 +78,7 @@ class HandshakeVerifier { /** * Verify the Upgrade request to WebSockets. - * @param string MUST equal "websocket" + * @param string $val MUST equal "websocket" * @return bool */ public function verifyUpgradeRequest($val) { @@ -87,7 +87,7 @@ class HandshakeVerifier { /** * Verify the Connection header - * @param string MUST equal "Upgrade" + * @param string $val MUST equal "Upgrade" * @return bool */ public function verifyConnection($val) { diff --git a/Version/RFC6455/Message.php b/Version/RFC6455/Message.php index e1c0593..fd20047 100644 --- a/Version/RFC6455/Message.php +++ b/Version/RFC6455/Message.php @@ -5,7 +5,7 @@ use Ratchet\WebSocket\Version\FrameInterface; class Message implements MessageInterface, \Countable { /** - * @var SplDoublyLinkedList + * @var \SplDoublyLinkedList */ protected $_frames; diff --git a/Version/VersionInterface.php b/Version/VersionInterface.php index 9a3c29e..ddc1170 100644 --- a/Version/VersionInterface.php +++ b/Version/VersionInterface.php @@ -10,9 +10,9 @@ use Guzzle\Http\Message\RequestInterface; interface VersionInterface extends MessageInterface { /** * Given an HTTP header, determine if this version should handle the protocol - * @param Guzzle\Http\Message\RequestInterface + * @param \Guzzle\Http\Message\RequestInterface $request * @return bool - * @throws UnderflowException If the protocol thinks the headers are still fragmented + * @throws \UnderflowException If the protocol thinks the headers are still fragmented */ function isProtocol(RequestInterface $request); @@ -24,16 +24,16 @@ interface VersionInterface extends MessageInterface { /** * Perform the handshake and return the response headers - * @param Guzzle\Http\Message\RequestInterface - * @return Guzzle\Http\Message\Response - * @throws UnderflowException If the message hasn't finished buffering (not yet implemented, theoretically will only happen with Hixie version) + * @param \Guzzle\Http\Message\RequestInterface $request + * @return \Guzzle\Http\Message\Response + * @throws \UnderflowException If the message hasn't finished buffering (not yet implemented, theoretically will only happen with Hixie version) */ function handshake(RequestInterface $request); /** - * @param Ratchet\ConnectionInterface - * @param Ratchet\MessageInterface - * @return Ratchet\ConnectionInterface + * @param \Ratchet\ConnectionInterface $conn + * @param \Ratchet\MessageInterface $coalescedCallback + * @return \Ratchet\ConnectionInterface */ function upgradeConnection(ConnectionInterface $conn, MessageInterface $coalescedCallback); diff --git a/VersionManager.php b/VersionManager.php index e3b93c9..ec81a9d 100644 --- a/VersionManager.php +++ b/VersionManager.php @@ -22,8 +22,9 @@ class VersionManager { /** * Get the protocol negotiator for the request, if supported - * @param Guzzle\Http\Message\RequestInterface - * @return Ratchet\WebSocket\Version\VersionInterface + * @param \Guzzle\Http\Message\RequestInterface $request + * @throws \InvalidArgumentException + * @return \Ratchet\WebSocket\Version\VersionInterface */ public function getVersion(RequestInterface $request) { foreach ($this->versions as $version) { @@ -36,7 +37,7 @@ class VersionManager { } /** - * @param Guzzle\Http\Message\RequestInterface + * @param \Guzzle\Http\Message\RequestInterface * @return bool */ public function isVersionEnabled(RequestInterface $request) { @@ -51,8 +52,8 @@ class VersionManager { /** * Enable support for a specific version of the WebSocket protocol - * @param Ratchet\WebSocket\Version\VersionInterface - * @return HandshakeNegotiator + * @param \Ratchet\WebSocket\Version\VersionInterface $version + * @return VersionManager */ public function enableVersion(VersionInterface $version) { $this->versions[$version->getVersionNumber()] = $version; @@ -68,8 +69,8 @@ class VersionManager { /** * Disable support for a specific WebSocket protocol version - * @param int The version ID to un-support - * @return HandshakeNegotiator + * @param int $versionId The version ID to un-support + * @return VersionManager */ public function disableVersion($versionId) { unset($this->versions[$versionId]); diff --git a/WsServer.php b/WsServer.php index 7577ef6..409259b 100644 --- a/WsServer.php +++ b/WsServer.php @@ -29,12 +29,12 @@ class WsServer implements MessageComponentInterface { /** * Decorated component - * @var Ratchet\MessageComponentInterface + * @var \Ratchet\MessageComponentInterface */ protected $_decorating; /** - * @var SplObjectStorage + * @var \SplObjectStorage */ protected $connections; @@ -47,7 +47,7 @@ class WsServer implements MessageComponentInterface { /** * UTF-8 validator - * @var Ratchet\WebSocket\Encoding\ValidatorInterface + * @var \Ratchet\WebSocket\Encoding\ValidatorInterface */ protected $validator; @@ -58,7 +58,7 @@ class WsServer implements MessageComponentInterface { private $isSpGenerated = false; /** - * @param Ratchet\MessageComponentInterface Your application to run with WebSockets + * @param \Ratchet\MessageComponentInterface $component 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) { @@ -155,7 +155,7 @@ class WsServer implements MessageComponentInterface { /** * Disable a specific version of the WebSocket protocol - * @param int Version ID to disable + * @param int $versionId Version ID to disable * @return WsServer */ public function disableVersion($versionId) { @@ -192,7 +192,7 @@ class WsServer implements MessageComponentInterface { } /** - * @param Traversable + * @param \Traversable|null $requested * @return string */ protected function getSubProtocolString(\Traversable $requested = null) { @@ -213,8 +213,9 @@ class WsServer implements MessageComponentInterface { /** * Close a connection with an HTTP response - * @param Ratchet\ConnectionInterface - * @param int HTTP status code + * @param \Ratchet\ConnectionInterface $conn + * @param int $code HTTP status code + * @return void */ protected function close(ConnectionInterface $conn, $code = 400) { $response = new Response($code, array(