Documentation for internal APIs

Author: clue

src/Io/ResponseParser.php

@@ -4,22 +4,46 @@
 
 use Psr\Http\Message\ResponseInterface;
 
+/**
+ * ResponseParser is a simple helper to return the buffered body of HTTP response objects
+ *
+ * @internal
+ * @see StreamingParser for working with streaming bodies
+ */
 class ResponseParser
 {
+    /**
+     * Returns the plain text body of the given $response
+     *
+     * @param ResponseInterface $response
+     * @return string
+     */
     public function expectPlain(ResponseInterface $response)
     {
         // text/plain
 
         return (string)$response->getBody();
     }
 
+    /**
+     * Returns the parsed JSON body of the given $response
+     *
+     * @param ResponseInterface $response
+     * @return array
+     */
     public function expectJson(ResponseInterface $response)
     {
         // application/json
 
         return json_decode((string)$response->getBody(), true);
     }
 
+    /**
+     * Returns the empty plain text body of the given $response
+     *
+     * @param ResponseInterface $response
+     * @return string
+     */
     public function expectEmpty(ResponseInterface $response)
     {
         // 204 No Content

src/Io/StreamingParser.php

@@ -12,8 +12,21 @@
 use Clue\React\Promise\Stream;
 use Psr\Http\Message\ResponseInterface;
 
+/**
+ * StreamingParser is a simple helper to work with the streaming body of HTTP response objects
+ *
+ * @internal
+ * @see ResponseParser for working with buffered bodies
+ */
 class StreamingParser
 {
+    /**
+     * Returns a readable JSON stream for the given ResponseInterface
+     *
+     * @param PromiseInterface $promise Promise<ResponseInterface>
+     * @return ReadableStreamInterface
+     * @uses self::parsePlainSream()
+     */
     public function parseJsonStream(PromiseInterface $promise)
     {
         // application/json
@@ -56,6 +69,12 @@ public function parseJsonStream(PromiseInterface $promise)
         return $out;
     }
 
+    /**
+     * Returns a readable plain text stream for the given ResponseInterface
+     *
+     * @param PromiseInterface $promise Promise<ResponseInterface>
+     * @return ReadableStreamInterface
+     */
     public function parsePlainStream(PromiseInterface $promise)
     {
         // text/plain
@@ -65,6 +84,13 @@ public function parsePlainStream(PromiseInterface $promise)
         }));
     }
 
+    /**
+     * Returns a promise which resolves with an array of all "progress" events
+     *
+     * @param ReadableStreamInterface $stream
+     * @param string                  $progressEventName the name of the event to collect
+     * @return PromiseInterface Promise<array, Exception>
+     */
     public function deferredStream(ReadableStreamInterface $stream, $progressEventName)
     {
         // cancelling the deferred will (try to) close the stream