improved documentation

Author: valtlfelipe

doc/activity.md

@@ -0,0 +1,51 @@
+## Activity API (incomplete)
+[Back to the navigation](index.md)
+
+Access to Starring and Watching a Repository for authenticated users.
+Wrap [GitHub Activity API](https://developer.github.com/v3/activity/).
+
+> No authentication required.
+
+### Get repos that a specific user has starred
+
+```php
+$users = $client->api('user')->starred('ornicar');
+```
+
+Returns an array of starred repos.
+
+> Requires [authentication](security.md).
+
+### Get repos that a authenticated user has starred
+
+```php
+$activity = $client->api('current_user')->starred()->all();
+```
+Returns an array of starred repos.
+
+### Check if authenticated user has starred a specific repo
+
+```php
+$owner = "KnpLabs";
+$repo = "php-github-api";
+$activity = $client->api('current_user')->starred()->check($owner, $repo);
+```
+Throws an Exception with code 404 in case that the repo is not starred by the authenticated user or NULL in case that it is starred by the authenticated user.
+
+### Star a specific repo for authenticated user
+
+```php
+$owner = "KnpLabs";
+$repo = "php-github-api";
+$activity = $client->api('current_user')->starred()->star($owner, $repo);
+```
+Throws an Exception in case of failure or NULL in case of success.
+
+### Unstar a specific repo for authenticated user
+
+```php
+$owner = "KnpLabs";
+$repo = "php-github-api";
+$activity = $client->api('current_user')->starred()->unstar($owner, $repo);
+```
+Throws an Exception in case of failure or NULL in case of success.

doc/index.md

@@ -20,6 +20,7 @@ APIs:
     * [Assets](repo/assets.md)
 * [Users](users.md)
 * [Meta](meta.md)
+* [Activity](activity.md)
 
 Additional features:
 

doc/users.md

@@ -108,6 +108,7 @@ $client->api('current_user')->follow()->unfollow('symfony');
 Returns an array of followed users.
 
 ### Get repos that a specific user is watching
+> See [more](activity.md).
 
 ```php
 $users = $client->api('user')->watched('ornicar');
@@ -124,6 +125,7 @@ $users = $client->api('current_user')->watched();
 Returns an array of watched repos.
 
 ### Get repos that a specific user has starred
+> See [more](activity.md).
 
 ```php
 $users = $client->api('user')->starred('ornicar');