Add basic documentation for internal classes

Author: clue

src/Io/ChunkedDecoder.php

@@ -8,7 +8,13 @@
 use React\Stream\WritableStreamInterface;
 use Exception;
 
-/** @internal */
+/**
+ * [Internal] Decodes "Transfer-Encoding: chunked" from given stream and returns only payload data.
+ *
+ * This is used internally to decode incoming requests with this encoding.
+ *
+ * @internal
+ */
 class ChunkedDecoder extends EventEmitter implements ReadableStreamInterface
 {
     const CRLF = "\r\n";

src/Io/ChunkedEncoder.php

@@ -7,7 +7,13 @@
 use React\Stream\Util;
 use React\Stream\WritableStreamInterface;
 
-/** @internal */
+/**
+ * [Internal] Encodes given payload stream with "Transfer-Encoding: chunked" and emits encoded data
+ *
+ * This is used internally to encode outgoing requests with this encoding.
+ *
+ * @internal
+ */
 class ChunkedEncoder extends EventEmitter implements ReadableStreamInterface
 {
     private $input;

src/Io/CloseProtectionStream.php

@@ -8,8 +8,12 @@
 use React\Stream\WritableStreamInterface;
 
 /**
+ * [Internal] Protects a given stream from actually closing and only pauses it instead.
+ *
+ * This is used internally to prevent the underlying connection from closing, so
+ * that we can still send back a response over the same stream.
+ *
  * @internal
- * This stream is used to protect the passed stream against closing.
  * */
 class CloseProtectionStream extends EventEmitter implements ReadableStreamInterface
 {

src/Io/HttpBodyStream.php

@@ -9,12 +9,20 @@
 use React\Stream\WritableStreamInterface;
 
 /**
+ * [Internal] Bridge between StreamInterface from PSR-7 and ReadableStreamInterface from ReactPHP
+ *
+ * This class is used in the server to stream the body of an incoming response
+ * from the client. This allows us to stream big amounts of data without having
+ * to buffer this data. Similarly, this used to stream the body of an outgoing
+ * request body to the client. The data will be sent directly to the client.
+ *
+ * Note that this is an internal class only and nothing you should usually care
+ * about. See the `StreamInterface` and `ReadableStreamInterface` for more
+ * details.
+ *
+ * @see StreamInterface
+ * @see ReadableStreamInterface
  * @internal
- * Uses a StreamInterface from PSR-7 and a ReadableStreamInterface from ReactPHP
- * to use PSR-7 objects and use ReactPHP streams
- * This is class is used in `HttpServer` to stream the body of a response
- * to the client. Because of this you can stream big amount of data without
- * necessity of buffering this data. The data will be send directly to the client.
  */
 class HttpBodyStream extends EventEmitter implements StreamInterface, ReadableStreamInterface
 {
@@ -23,8 +31,8 @@ class HttpBodyStream extends EventEmitter implements StreamInterface, ReadableSt
     private $size;
 
     /**
-     * @param ReadableStreamInterface $input - Stream data from $stream as a body of a PSR-7 object4
-     * @param int|null $size - size of the data body
+     * @param ReadableStreamInterface $input Stream data from $stream as a body of a PSR-7 object4
+     * @param int|null $size size of the data body
      */
     public function __construct(ReadableStreamInterface $input, $size)
     {

src/Io/LengthLimitedStream.php

@@ -7,7 +7,14 @@
 use React\Stream\Util;
 use React\Stream\WritableStreamInterface;
 
-/** @internal */
+/**
+ * [Internal] Limits the amount of data the given stream can emit
+ *
+ * This is used internally to limit the size of the underlying connection stream
+ * to the size defined by the "Content-Length" header of the incoming request.
+ *
+ * @internal
+ */
 class LengthLimitedStream extends EventEmitter implements ReadableStreamInterface
 {
     private $stream;

src/Io/MultipartParser.php

@@ -6,6 +6,11 @@
 use RingCentral\Psr7;
 
 /**
+ * [Internal] Parses a string body with "Content-Type: multipart/form-data" into structured data
+ *
+ * This is use internally to parse incoming request bodies into structured data
+ * that resembles PHP's `$_POST` and `$_FILES` superglobals.
+ *
  * @internal
  */
 final class MultipartParser

src/Io/RequestHeaderParser.php

@@ -7,6 +7,11 @@
 use Exception;
 
 /**
+ * [Internal] Parses an incoming request header from an input stream
+ *
+ * This is used internally to parse the request header from the connection and
+ * then process the remaining connection as the request body.
+ *
  * @event headers
  * @event error
  *

src/Io/ServerRequest.php

@@ -5,7 +5,20 @@
 use Psr\Http\Message\ServerRequestInterface;
 use RingCentral\Psr7\Request;
 
-/** @internal */
+/**
+ * [Internal] Implementation of the PSR-7 `ServerRequestInterface`
+ *
+ * This is used internally to represent each incoming request message.
+ *
+ * This implementation builds on top of an existing outgoing request message and
+ * only adds required server methods.
+ *
+ * Note that this is an internal class only and nothing you should usually care
+ * about. See the `ServerRequestInterface` for more details.
+ *
+ * @see ServerRequestInterface
+ * @internal
+ */
 class ServerRequest extends Request implements ServerRequestInterface
 {
     private $attributes = array();

src/Io/UploadedFile.php

@@ -8,6 +8,14 @@
 use RuntimeException;
 
 /**
+ * [Internal] Implementation of the PSR-7 `UploadedFileInterface`
+ *
+ * This is used internally to represent each incoming file upload.
+ *
+ * Note that this is an internal class only and nothing you should usually care
+ * about. See the `UploadedFileInterface` for more details.
+ *
+ * @see UploadedFileInterface
  * @internal
  */
 final class UploadedFile implements UploadedFileInterface