Improve documentation for RT::Search modules

The new RT::Search test page in the web UI may lead
users to read the documentation for the search modules,
so clean up and improve those pages.

lib/RT/Search/ActiveTicketsInQueue.pm

@@ -48,19 +48,22 @@
 
 =head1 NAME
 
-  RT::Search::ActiveTicketsInQueue
+RT::Search::ActiveTicketsInQueue
 
 =head1 SYNOPSIS
 
+    rt-crontool --search RT::Search::ActiveTicketsInQueue \
+        --search-arg "General" \
+        --action RT::Action \
+        --verbose \
+        --log debug
+
 =head1 DESCRIPTION
 
-Find all active tickets in the queue named in the argument passed in
+Find all active tickets in the queue named in the provided Argument.
 
 =head1 METHODS
 
-
-
-
 =cut
 
 package RT::Search::ActiveTicketsInQueue;
@@ -69,12 +72,30 @@ use strict;
 use warnings;
 use base qw(RT::Search);
 
+=head2 Describe
+
+Returns a localized string describing the module's function.
+
+=cut
 
 sub Describe  {
   my $self = shift;
-  return ($self->loc("No description for [_1]", ref $self));
+  return ($self->loc("Find active tickets in a queue [_1]", ref $self));
 }
 
+=head2 Prepare
+
+Runs a search on the associated L<RT::Tickets> object, limiting
+it to active tickets in the queue identified by the provided
+Argument.
+
+The search is performed in the context of the user running the
+command. For rt-crontool searches, this is the L<RT::User> account
+associated with the Linux account running rt-crontool via the
+"Unix login" setting.
+
+=cut
+
 sub Prepare  {
   my $self = shift;
 

lib/RT/Search/FromSQL.pm

@@ -48,18 +48,33 @@
 
 =head1 NAME
 
-  RT::Search::FromSQL
+RT::Search::FromSQL
 
 =head1 SYNOPSIS
 
-=head1 DESCRIPTION
+    rt-crontool --search RT::Search::FromSQL \
+        --search-arg "Owner = 'root'" \
+        --action RT::Action \
+        --verbose \
+        --log debug
 
-Find all tickets described by the SQL statement passed as an argument
+=head1 DESCRIPTION
 
-=head1 METHODS
+The FromSQL search performs a ticket search using the same
+mechanism as the RT Query Builder.
 
+It expects one Argument which is a TicketSQL string. Since the
+search is the same as the RT Query Builder, you can paste in
+a search directly from the Advanced tab. The search is then
+performed on the L<RT::Tickets> object associated with the running
+search.
 
+When running with a command-line utility such as
+rt-crontool, you may need to apply shell escapes or make
+other format changes to correctly pass special characters
+through the shell.
 
+=head1 METHODS
 
 =cut
 
@@ -82,9 +97,13 @@ sub Describe  {
 
 =head2 Prepare
 
-The meat of the module.  Runs a search on its Tickets object, using
-the SQL string described in its Argument object.  The Tickets object
-is reduced to those tickets matching the SQL query.
+Runs a search on the associated L<RT::Tickets> object, using
+the TicketSQL string provided in the Argument.
+
+The search is performed in the context of the user running the
+command. For rt-crontool searches, this is the L<RT::User> account
+associated with the Linux account running rt-crontool via the
+"Unix login" setting.
 
 =cut
 

lib/RT/Search/Simple.pm

@@ -48,13 +48,29 @@
 
 =head1 NAME
 
-  RT::Search::Simple
+RT::Search::Simple
 
 =head1 SYNOPSIS
 
+    rt-crontool --search RT::Search::Simple \
+        --search-arg "23" \
+        --action RT::Action \
+        --verbose \
+        --log debug
+
 =head1 DESCRIPTION
 
-Use the argument passed in as a simple set of keywords
+The Simple search performs a ticket search using the same mechanism as
+the "Simple Search" web UI.
+
+It expects one Argument which is a string representing the search term.
+The behavior varies a bit depending on RT configuration and user
+preference, check out ticket "Simple Search" page that contains syntax
+and behavior details.
+
+When running with a command-line utility such as rt-crontool, you may
+need to apply shell escapes or make other format changes to correctly
+pass special characters through the shell.
 
 =head1 METHODS
 
@@ -84,11 +100,30 @@ sub _Init {
     $self->SUPER::_Init(%args);
 }
 
+=head2 Describe
+
+Returns a localized string describing the module's function.
+
+=cut
+
 sub Describe {
     my $self = shift;
     return ( $self->loc( "Keyword and intuition-based searching", ref $self ) );
 }
 
+
+=head2 Prepare
+
+Runs a simple search on the associated L<RT::Tickets> object, using
+the string provided in the Argument.
+
+The search is performed in the context of the user running the
+command. For rt-crontool searches, this is the L<RT::User> account
+associated with the Linux account running rt-crontool via the
+"Unix login" setting.
+
+=cut
+
 sub Prepare {
     my $self = shift;
     my $tql  = $self->QueryToSQL( $self->Argument );