update documentation for get_usertag

[debbugs.git] / Debbugs / SOAP.pm

diff --git a/Debbugs/SOAP.pm b/Debbugs/SOAP.pm
index fc6af2ec9e93a343fd4ba4214f2b8155702318dc..ed669a125f64d9c6768efedf6caa8327f384250f 100644 (file)
--- a/Debbugs/SOAP.pm
+++ b/Debbugs/SOAP.pm
@@ -52,10 +52,13 @@ our %DEBBUGS_SOAP_COOKIES;
 =head2 get_usertag
 
      my %ut = get_usertag('don@donarmstrong.com','this-bug-sucks','eat-this-bug');
+     my %ut = get_usertag('don@donarmstrong.com');
 
 Returns a hashref of bugs which have the specified usertags for the
 user set.
 
+In the second case, returns all of the usertags for the user passed.
+
 =cut
 
 use Debbugs::User qw(read_usertags);
@@ -108,8 +111,14 @@ sub get_status {
 =head2 get_bugs
 
      my @bugs = get_bugs(...);
+     my @bugs = get_bugs([...]);
+
+Returns a list of bugs. In the second case, allows the variable
+parameters to be specified as an array reference in case your favorite
+language's SOAP implementation is craptacular.
 
-See L<Debbugs::Bugs::get_bugs> for details.
+See L<Debbugs::Bugs::get_bugs> for details on what C<...> actually
+means.
 
 =cut
 
@@ -118,6 +127,11 @@ use Debbugs::Bugs qw();
 sub get_bugs{
      my $VERSION = __populate_version(pop);
      my ($self,@params) = @_;
+     # Because some soap implementations suck and can't handle
+     # variable numbers of arguments we allow get_bugs([]);
+     if (@params == 1 and ref($params[0]) eq 'ARRAY') {
+         @params = @{$params[0]};
+     }
      my %params;
      # Because some clients can't handle passing arrayrefs, we allow
      # options to be specified multiple times
@@ -136,6 +150,22 @@ sub get_bugs{
      return \@bugs;
 }
 
+=head2 newest_bugs
+
+     my @bugs = newest_bugs(5);
+
+Returns a list of the newest bugs. [Note that all bugs are *not*
+guaranteed to exist, but they should in the most common cases.]
+
+=cut
+
+sub newest_bugs{
+     my $VERSION = __populate_version(pop);
+     my ($self,$num) = @_;
+     my $newest_bug = Debbugs::bugs::newest_bug();
+     return [($newest_bug - $num + 1) .. $newest_bug];
+
+}
 
 =head2 get_bug_log
 
@@ -159,12 +189,15 @@ the following
  ]
 
 
+Currently $msg_num is completely ignored.
+
 =cut
 
 use Debbugs::Log qw();
 use Debbugs::MIME qw(parse);
 
 sub get_bug_log{
+     my $VERSION = __populate_version(pop);
      my ($self,$bug,$msg_num) = @_;
 
      my $location = getbuglocation($bug,'log');
@@ -182,9 +215,7 @@ sub get_bug_log{
      my @messages;
      while (my $record = $log->read_record()) {
          $current_msg++;
-         print STDERR "message $current_msg\n";
          #next if defined $msg_num and ($current_msg ne $msg_num);
-         print STDERR "still message $current_msg\n";
          next unless $record->{type} eq 'incoming-recv';
          my ($msg_id) = $record->{text} =~ /^Message-Id:\s+<(.+)>/im;
          next if defined $msg_id and exists $seen_msg_ids{$msg_id};
@@ -192,10 +223,8 @@ sub get_bug_log{
          next if defined $msg_id and $msg_id =~ /handler\..+\.ack(?:info)?\@/;
          my $message = parse($record->{text});
          my ($header,$body) = map {join("\n",make_list($_))}
-              values %{$message};
-         print STDERR "still still message $current_msg\n";
-         push @messages,{html => $record->{html},
-                         header => $header,
+              @{$message}{qw(header body)};
+         push @messages,{header => $header,
                          body   => $body,
                          attachments => [],
                          msg_num => $current_msg,