Update GitLab-API.md

pod/GitLab-API.md

 # NAME
 
-GitLab::API - lightweight GitLab API client.
+`GitLab::API` - lightweight GitLab API client.
 Also implements **Session** API to obtain authentication token if needed.
 Other modules are needed for additional methods.
 
@@ -12,17 +12,26 @@ See [GitLab API](http://doc.gitlab.com/ce/api/) for details.
 use GitLab::API;
 use GitLab::Users;
 use GitLab::Groups;
+use GitLab::Projects;
 
 my $gitlab = GitLab::API->new(AuthToken => $token);
+
+# simple result
 my $groups = $gitlab->groups(search => "awesome-group");
 
 die("Failed to get groups") unless defined $groups;
 
+# result with response
 my ($users, $response) = $gitlab->users(-response => 1);
 
 die("Request failed: " . $response->message) unless $response->is_success;
 
-# do something with users or groups
+# iterator for paginated responses
+my $projects = $gitlab->projects(-iterator => 1);
+
+while (my $project = $projects->next) {
+    # ...
+}
 ```
 
 # DESCRIPTION
@@ -76,7 +85,7 @@ die("Request failed: " . $response->message) unless $response->is_success;
 - `whoami()`
 
     Returns the user whose authentication key is used for the request (or impersonated user if [`sudo`](#sudo) is in effect).
-    See ["REQUEST METHODS"](#request-methods) below.
+    See [REQUEST METHODS](#request-methods) below.
 
 - `is_admin()`
 
@@ -185,10 +194,20 @@ The following methods are intended to be called from additional methods implemen
     - `-page => N`
 
         When used with paginated requests, returns only entries from the given page.
-        The number of entities in each page is always _100_ except (of course) the last one.
+        The number of entities in each page is by default _50_ except (of course) the last one.
+        It is possible to change the default page size with the `-per_page` option.
         The API returns an empty response for invalid page numbers.
 
-        The method carps if used with a template without `$tmpl->{paginated}` attribute.
+        The method _croaks_ if used with a template without `$tmpl->{paginated}` attribute or if combined with `-iterator`.
+        
+    - `-per_page => N`
+    
+        Change the page size for `-page` or `-iterator` options.
+        The maximum allowed value by GitLab is currently `100`.
+        
+    - `-iterator`
+    
+        When non-zero, return an instance of [`GitLab::API::Iterator`](GitLab-API-Iterator.md) that will sequentially request pages when needed.
 
 # Package methods
 
@@ -398,4 +417,4 @@ Roman Lacko <[`xlacko1@fi.muni.cz`](mailto:xlacko1@fi.muni.cz)>
 
 - [GitLab](pod-GitLab.md)
 
-    Wrapper around `GitLab::API`
+    Wrapper around `GitLab::API`.