--- trunk/Nos.pm	2005/06/21 20:49:27	59
+++ trunk/Nos.pm	2005/06/22 12:31:45	62
@@ -40,7 +40,39 @@
 
 =head1 DESCRIPTION
 
-Core module for notice sender's functionality.
+Notice sender is mail handler. It is not MTA, since it doesn't know how to
+receive e-mails or send them directly to other hosts. It is not mail list
+manager because it requires programming to add list members and send
+messages. You can think of it as mechanisam for off-loading your e-mail
+sending to remote server using SOAP service.
+
+It's concept is based around B<lists>. Each list can have zero or more
+B<members>. Each list can have zero or more B<messages>.
+
+Here comes a twist: each outgoing message will have unique e-mail generated,
+so Notice Sender will be able to link received replies (or bounces) with
+outgoing messages.
+
+It doesn't do much more than that. It B<can't> create MIME encoded e-mail,
+send attachments, handle 8-bit characters in headers (which have to be
+encoded) or anything else.
+
+It will just queue your e-mail message to particular list (sending it to
+possibly remote Notice Sender SOAP server just once), send it out at
+reasonable rate (so that it doesn't flood your e-mail infrastructure) and
+track replies.
+
+It is best used to send smaller number of messages to more-or-less fixed
+list of recipients while allowing individual responses to be examined.
+Tipical use include replacing php e-mail sending code with SOAP call to
+Notice Sender. It does support additional C<ext_id> field for each member
+which can be used to track some unique identifier from remote system for
+particular user.
+
+It comes with command-line utility C<sender.pl> which can be used to perform
+all available operation from scripts (see C<perldoc sender.pl>).
+This command is also useful for debugging while writing client SOAP
+application.
 
 =head1 METHODS
 
@@ -99,7 +131,7 @@
 
 Returns ID of newly created list.
 
-Calls internally L<_add_list>, see details there.
+Calls internally C<_add_list>, see details there.
 
 =cut
 
@@ -203,7 +235,7 @@
  }
 
 If list is not found, returns false. If there is C<ext_id> in user data,
-that will also be returned.
+it will also be returned.
 
 =cut
 
@@ -252,6 +284,9 @@
 
 Returns false if user doesn't exist.
 
+This function will delete member from all lists (by cascading delete), so it
+shouldn't be used lightly.
+
 =cut
 
 sub delete_member {
@@ -308,7 +343,7 @@
 	my $this_user = $user->search( email => $args->{'email'} )->first || croak "can't find user: ".$args->{'email'};
 	my $this_list = $list->search( name => $args->{'list'} )->first || croak "can't find list: ".$args->{'list'};
 
-	my $this_user_list = $user_list->search_where( list_id => $this_list->id, user_id => $this_list->id )->first || return;
+	my $this_user_list = $user_list->search_where( list_id => $this_list->id, user_id => $this_user->id )->first || return;
 
 	$this_user_list->delete || croak "can't delete user from list\n";
 
@@ -515,6 +550,8 @@
 	message => $message,
  );
 
+This method is used by C<sender.pl> when receiving e-mail messages.
+
 =cut
 
 sub inbox_message {
@@ -764,6 +801,10 @@
 
 Returns array of hashes with user informations, see C<list_members>.
 
+Returning arrays from SOAP calls is somewhat fuzzy (at least to me). It
+seems that SOAP::Lite client thinks that it has array with one element which
+is array of hashes with data.
+
 =cut
 
 sub ListMembers {
@@ -777,9 +818,32 @@
 		$list_name = $_[0]->{'list'};
 	}
 
-	return $nos->list_members( list => $list_name );
+	return [ $nos->list_members( list => $list_name ) ];
+}
+
+
+=head2 DeleteMemberFromList
+
+ $member_id = DeleteMemberFromList(
+	list => 'My list',
+	email => 'e-mail@example.com',
+ );
+
+=cut
+
+sub DeleteMemberFromList {
+	my $self = shift;
+
+	if ($_[0] !~ m/^HASH/) {
+		return $nos->delete_member_from_list(
+			list => $_[0], email => $_[1],
+		);
+	} else {
+		return $nos->delete_member_from_list( %{ shift @_ } );
+	}
 }
 
+
 =head2 AddMessageToList
 
  $message_id = AddMessageToList(