diff --git a/doc/issue/comments.md b/doc/issue/comments.md
index f976047b885..9a5f7b1d851 100644
--- a/doc/issue/comments.md
+++ b/doc/issue/comments.md
@@ -9,8 +9,24 @@ Wraps [GitHub Issue Comments API](http://developer.github.com/v3/issues/comments
 $comments = $client->api('issue')->comments()->all('KnpLabs', 'php-github-api', 4);
 ```
 
-List an issue comments by username, repo and issue number.
-Returns an array of issues.
+* `KnpLabs` : the owner of the repository
+* `php-github-api` : the name of the repository
+* `4` : the id of the issue
+* You can select another page of comments using one more parameter (default: 1)
+
+Returns an array of comments.
+
+
+### Show an issue comment
+
+```php
+$comment = $client->api('issue')->comments()->show('KnpLabs', 'php-github-api', 33793831);
+```
+
+* `KnpLabs` : the owner of the repository
+* `php-github-api` : the name of the repository
+* `33793831` : the id of the comment
+
 
 ### Add a comment on an issue
 
@@ -23,5 +39,36 @@ Returns an array of issues.
 $client->api('issue')->comments()->create('KnpLabs', 'php-github-api', 4, array('body' => 'My new comment'));
 ```
 
-Add a comment to the issue by username, repo and issue number and array with comment data: `body`
-and optionally `title`.
+* `KnpLabs` : the owner of the repository
+* `php-github-api` : the name of the repository
+* `4` : the id of the issue
+* You can set a `body` and optionally a `title`
+
+
+### Update a comment on an issue
+
+> **Note:**
+
+> Requires [authentication](../security.md).
+
+```php
+$client->api('issue')->comments()->create('KnpLabs', 'php-github-api', 33793831, array('body' => 'My updated comment'));
+```
+
+* `KnpLabs` : the owner of the repository
+* `php-github-api` : the name of the repository
+* `33793831` : the id of the comment
+
+### Remove a comment on an issue
+
+> **Note:**
+
+> Requires [authentication](../security.md).
+
+```php
+$client->api('issue')->comments()->remove('KnpLabs', 'php-github-api', 33793831);
+```
+
+* `KnpLabs` : the owner of the repository
+* `php-github-api` : the name of the repository
+* `33793831` : the id of the comment
\ No newline at end of file