minor documentation and logging changes in API(::Iterator)

GitLab/API.pm

@@ -77,6 +77,7 @@ sub new {
     croak "GitLab authentication failed: ", $response->message
         unless $response->is_success;
 
+    $self->{user_is_admin} = $user->{is_admin};
     my $version = $self->version(-immortal => 1);
 
     my $vn = defined $version
@@ -91,6 +92,9 @@ sub new {
 sub sudo {
     my ($self, $who) = @_;
 
+    carp "Using sudo() without administrator privileges"
+        if defined $who && !$self->is_admin;
+
     $log->debug(defined $who ? "impersonating '$who'" : "stopped impersonation");
     $self->http->default_header(SUDO => $who);
     $self->{impersonate} = $who;
@@ -111,13 +115,7 @@ sub die_on_error {
 
 sub is_admin {
     my ($self) = @_;
-    my $sudo = $self->{impersonate};
-
-    $self->sudo()      if defined $sudo;
-    my $user = $self->whoami();
-    $self->sudo($sudo) if defined $sudo;
-
-    return defined $user && $user->{is_admin};
+    return $self->{user_is_admin};
 }
 
 #===============================================================================
@@ -275,6 +273,7 @@ sub exec_request {
         croak "Unsupported method '$tmpl->{method}'";
     }
 
+    # dump HTTP request and response if using trace
     if ($log->is_trace) {
         $log->trace("----  HTTP REQUEST  ".("-" x 25)."\n".$response->request->as_string);
         $log->trace("----  HTTP RESPONSE ".("-" x 25)."\n".$response->as_string);
@@ -597,7 +596,7 @@ Unless specified otherwise, these methods take a hash of options, e.g.
 
 Generally, keys starting with the C<-> (minus) characters are intended to modify the underlying C</exec_request>'s behaviour and are not forwarded to GitLab.
 
-This module contains only the L</whoami> API method, other methods are provided
+This module contains only L</whoami> and L</version> API methods, other methods are provided
 by additional C<GitLab::*> modules.
 
 =head1 REQUEST TEMPLATES
@@ -757,8 +756,8 @@ Complete GitLab API v3 implementation with CLI support.
 
 =item L<GitLab>
 
-    use GitLab LIST;
+    use GitLab;
 
-Wrapper around L<GitLab::API> that loads all GitLab modules in the C<LIST>.
+Wrapper around L<GitLab::API> that loads all GitLab modules.
 
 =back

GitLab/API/Iterator.pm

@@ -28,7 +28,7 @@ sub new {
 
     bless $self, $class;
 
-    $self->idebug("created for \"$url\", per_page=$self->{per_page}");
+    $self->idebug("created url=\"$url\", per_page=$self->{per_page}");
     $self->reset;
 
     return $self;
@@ -40,7 +40,7 @@ sub count   { return shift->{count}; }
 sub name    { return shift->{tmpl}->{name}; }
 sub pages   { return shift->{pages_read};   }
 
-sub idebug  { $log->debug("(" . shift->name . ") " . join("", @_)); }
+sub idebug  { $log->debug("<" . shift->name . "> " . join("", @_)); }
 
 #===============================================================================
 #   Public methods
@@ -50,7 +50,7 @@ sub next {
     my ($self) = @_;
 
     if ($self->{ix} + 1 == $self->count && ($self->{finished} || !$self->next_block)) {
-        $self->idebug("iterator finished, nothing to do");
+        $self->idebug("already finished, nothing to do");
         return;
     }
 
@@ -61,7 +61,7 @@ sub next {
 sub reset {
     my ($self) = @_;
 
-    $self->idebug("resetting interator");
+    $self->idebug("resetting");
     $self->{data}           = [];
     $self->{ix}             = -1;
     $self->{count}          =  0;
@@ -117,10 +117,10 @@ sub next_block {
         return 0;
     }
 
-    $self->idebug("requesting a new block, currently has $self->{pages_read} / " . ($self->{pages_total} // "unknown"));
+    $self->idebug("requesting a new block, has=$self->{pages_read} total=" . ($self->{pages_total} // "unknown"));
 
     if (defined $self->{pages_total} && $self->{pages_total} == $self->{pages_read}) {
-        $self->idebug("all pages were read, nothing to do");
+        $self->idebug("nothing to do");
         $self->{finished} = 1;
         return 0;
     }
@@ -143,7 +143,7 @@ sub next_block {
     if (!$response->is_success) {
         $self->{good} = 0;
 
-        croak "Cannot obtain next block for (" . $self->name . "): " . $response->status_line
+        croak "Cannot obtain next block for '" . $self->name . "': " . $response->status_line
             if $self->api->die_on_error;
         return 0;
     }
@@ -157,7 +157,7 @@ sub next_block {
         # use 1 if there are data, 0 otherwise
         my $default = @$data ? 1 : 0;
         $self->{pages_total} = $response->header("X-Total-Pages") // $default;
-        $self->idebug("total pages $self->{pages_total}");
+        $self->idebug("pages_total=$self->{pages_total}");
     }
 
     push @{$self->{data}},      @$data;
@@ -171,7 +171,10 @@ sub next_block {
 
     $self->{finished} = !$self->{pages_total} || $self->{pages_read} == $self->{pages_total};
     $self->idebug("block read successful");
-    $self->idebug("all blocks were read") if $self->{finished};
+
+    $self->idebug("finished")
+        if $self->{finished};
+
     return 1;
 }