Add support for pagination and parameters in the pull request comments API. (#576)

* Add support for pagination and parameters to review comments API.

* Add  doc blocks and links.

Author: a-ast

lib/Github/Api/PullRequest/Comments.php

@@ -38,20 +38,64 @@ public function configure($bodyType = null, $apiVersion = null)
         return $this;
     }
 
-    public function all($username, $repository, $pullRequest = null)
+    /**
+     * Get a listing of a pull request's comments by the username, repository and pull request number
+     * or all repository comments by the username and repository.
+     *
+     * @link https://developer.github.com/v3/pulls/comments/#list-comments-on-a-pull-request
+     * @link https://developer.github.com/v3/pulls/comments/#list-comments-in-a-repository
+     *
+     * @param string   $username    the username
+     * @param string   $repository  the repository
+     * @param int|null $pullRequest the pull request number
+     * @param array    $params      a list of extra parameters.
+     *
+     * @return array
+     */
+    public function all($username, $repository, $pullRequest = null, array $params = [])
     {
         if (null !== $pullRequest) {
             return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/pulls/'.rawurlencode($pullRequest).'/comments');
         }
 
-        return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/pulls/comments');
+        $parameters = array_merge([
+            'page' => 1,
+            'per_page' => 30
+        ], $params);
+
+        return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/pulls/comments', $parameters);
     }
 
+    /**
+     * Get a single pull request comment by the username, repository and comment id.
+     *
+     * @link https://developer.github.com/v3/pulls/comments/#get-a-single-comment
+     *
+     * @param string $username   the username
+     * @param string $repository the repository
+     * @param int    $comment    the comment id
+     *
+     * @return array
+     */
     public function show($username, $repository, $comment)
     {
         return $this->get('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/pulls/comments/'.rawurlencode($comment));
     }
 
+    /**
+     * Create a pull request comment by the username, repository and pull request number.
+     *
+     * @link https://developer.github.com/v3/pulls/comments/#create-a-comment
+     *
+     * @param string $username    the username
+     * @param string $repository  the repository
+     * @param int    $pullRequest the pull request number
+     * @param array  $params      a list of extra parameters.
+     *
+     * @throws MissingArgumentException
+     *
+     * @return array
+     */
     public function create($username, $repository, $pullRequest, array $params)
     {
         if (!isset($params['body'])) {
@@ -66,6 +110,20 @@ public function create($username, $repository, $pullRequest, array $params)
         return $this->post('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/pulls/'.rawurlencode($pullRequest).'/comments', $params);
     }
 
+    /**
+     * Update a pull request comment by the username, repository and comment id.
+     *
+     * @link https://developer.github.com/v3/pulls/comments/#edit-a-comment
+     *
+     * @param string $username   the username
+     * @param string $repository the repository
+     * @param int    $comment    the comment id
+     * @param array  $params     a list of extra parameters.
+     *
+     * @throws MissingArgumentException
+     *
+     * @return array
+     */
     public function update($username, $repository, $comment, array $params)
     {
         if (!isset($params['body'])) {
@@ -75,6 +133,17 @@ public function update($username, $repository, $comment, array $params)
         return $this->patch('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/pulls/comments/'.rawurlencode($comment), $params);
     }
 
+    /**
+     * Delete a pull request comment by the username, repository and comment id.
+     *
+     * @link https://developer.github.com/v3/pulls/comments/#delete-a-comment
+     *
+     * @param string $username   the username
+     * @param string $repository the repository
+     * @param int    $comment    the comment id
+     *
+     * @return string
+     */
     public function remove($username, $repository, $comment)
     {
         return $this->delete('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/pulls/comments/'.rawurlencode($comment));