From 500b95460ea781228f27aa2e329dbde6711a05a6 Mon Sep 17 00:00:00 2001
From: pate <pate>
Date: Fri, 20 Sep 2002 12:49:47 +0000
Subject: [PATCH] adding POD from Andres Arensburger

---
 C4/Database.pm |  28 +-
 C4/Koha.pm     |  93 +++--
 C4/Output.pm   | 158 ++++++++-
 C4/Search.pm   | 907 +++++++++++++++++++++++++++++++++++++++++++++++--
 4 files changed, 1130 insertions(+), 56 deletions(-)

diff --git a/C4/Database.pm b/C4/Database.pm
index e10b456206..63d828dcd2 100755
--- a/C4/Database.pm
+++ b/C4/Database.pm
@@ -1,4 +1,4 @@
-package C4::Database; #asummes C4/Database
+package C4::Database; #assumes C4/Database
 
 #requires DBI.pm to be installed
 
@@ -60,12 +60,28 @@ sub C4Connect  {
   return $dbh;
 } # sub C4Connect
 
+=item requireDBI
+
+  &requireDBI($dbh, $functionnname);
+
+Verifies that C<$dbh> is a valid DBI::db database handle (presumably
+to the Koha database). If it isn't, the function dies.
+
+C<$functionname> is the name of the calling function, which will be
+used in error messages.
+
+=cut
+#'
 #------------------
 # Helper subroutine to make sure database handle was passed properly
 sub requireDBI {
     my (
 	$dbh,
 	$subrname,	# name of calling subroutine
+			# FIXME - Ought to get this with 'caller',
+			# instead of requiring developers to always
+			# get it right. Plus, it'd give the line
+			# number.
     )=@_;
 
     unless ( ref($dbh) =~ /DBI::db/ ) {
@@ -77,3 +93,13 @@ sub requireDBI {
 
 
 END { }
+
+1;
+__END__
+=back
+
+=head1 SEE ALSO
+
+L<DBI(3)|DBI>
+
+=cut
diff --git a/C4/Koha.pm b/C4/Koha.pm
index a5abe88e8c..1503f48ce1 100644
--- a/C4/Koha.pm
+++ b/C4/Koha.pm
@@ -26,6 +26,30 @@ use vars qw($VERSION @ISA @EXPORT);
   
 $VERSION = 0.01;
     
+=head1 NAME
+
+C4::Koha - Perl Module containing convenience functions for Koha scripts
+
+=head1 SYNOPSIS
+
+  use C4::Koha;
+
+
+  $date = slashifyDate("01-01-2002")
+  $ethnicity = fixEthnicity('asian');
+  ($categories, $labels) = borrowercategories();
+  ($categories, $labels) = ethnicitycategories();
+
+=head1 DESCRIPTION
+
+Koha.pm provides many functions for Koha scripts.
+
+=head1 FUNCTIONS
+
+=over 2
+
+=cut
+
 @ISA = qw(Exporter);
 @EXPORT = qw(&slashifyDate
 	     &fixEthnicity
@@ -37,6 +61,15 @@ use vars qw();
 	
 my $DEBUG = 0;
 
+=item slashifyDate
+
+  $slash_date = &slashifyDate($dash_date);
+
+Takes a string of the form "DD-MM-YYYY" (or anything separated by
+dashes), converts it to the form "YYYY/MM/DD", and returns the result.
+
+=cut
+
 sub slashifyDate {
     # accepts a date of the form xx-xx-xx[xx] and returns it in the 
     # form xx/xx/xx[xx]
@@ -44,6 +77,17 @@ sub slashifyDate {
     return("$dateOut[2]/$dateOut[1]/$dateOut[0]")
 }
 
+=item fixEthnicity
+
+  $ethn_name = &fixEthnicity($ethn_code);
+
+Takes an ethnicity code (e.g., "european" or "pi") and returns the
+corresponding descriptive name from the C<ethnicity> table in the
+Koha database ("European" or "Pacific Islander").
+
+=cut
+#'
+
 sub fixEthnicity($) { 
 
     my $ethnicity = shift;
@@ -56,6 +100,18 @@ sub fixEthnicity($) {
     return $data->{'name'};
 }
 
+=item borrowercategories
+
+  ($codes_arrayref, $labels_hashref) = &borrowercategories();
+
+Looks up the different types of borrowers in the database. Returns two
+elements: a reference-to-array, which lists the borrower category
+codes, and a reference-to-hash, which maps the borrower category codes
+to category descriptions.
+
+=cut
+#'
+
 sub borrowercategories {
     my $dbh=C4Connect;
     my $sth=$dbh->prepare("Select categorycode,description from categories order by description");
@@ -71,6 +127,18 @@ sub borrowercategories {
     return(\@codes,\%labels);
 }
 
+=item ethnicitycategories
+
+  ($codes_arrayref, $labels_hashref) = &ethnicitycategories();
+
+Looks up the different ethnic types in the database. Returns two
+elements: a reference-to-array, which lists the ethnicity codes, and a
+reference-to-hash, which maps the ethnicity codes to ethnicity
+descriptions.
+
+=cut
+#'
+
 sub ethnicitycategories {
     my $dbh=C4Connect;
     my $sth=$dbh->prepare("Select code,name from ethnicity order by name");
@@ -89,25 +157,7 @@ sub ethnicitycategories {
 1;
 __END__
 
-=head1 NAME
-
-Koha - Perl Module containing convenience functions for Koha scripts
-
-=head1 SYNOPSIS
-
-  use Koha;
-
-
-  $date = slashifyDate("01-01-2002")
-  $ethnicity=fixEthnicity('asian');
-  ($categories,$labels)=borrowercategories();
-
-=head1 DESCRIPTION
-
-Koha.pm provides many functions for Koha scripts.
-
-slashifyDate() takes a dash separated date string and returns a slash 
-separated date string
+=back
 
 =head1 AUTHOR
 
@@ -118,8 +168,3 @@ Pat Eyler, pate@gnu.org
 perl(1).
 
 =cut
-
-
-
-
-
diff --git a/C4/Output.pm b/C4/Output.pm
index 8c6b7d747d..6aa7df5944 100644
--- a/C4/Output.pm
+++ b/C4/Output.pm
@@ -33,6 +33,28 @@ use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
 # set the version for version checking
 $VERSION = 0.01;
 
+=head1 NAME
+
+C4::Output - Functions for generating HTML for the Koha web interface
+
+=head1 SYNOPSIS
+
+  use C4::Output;
+
+  $str = &mklink("http://www.koha.org/", "Koha web page");
+  print $str;
+
+=head1 DESCRIPTION
+
+The functions in this module generate HTML, and return the result as a
+printable string.
+
+=head1 FUNCTIONS
+
+=over 2
+
+=cut
+
 @ISA = qw(Exporter);
 @EXPORT = qw(&startpage &endpage 
 	     &mktablehdr &mktableft &mktablerow &mklink
@@ -48,19 +70,21 @@ $VERSION = 0.01;
 # your exported package globals go here,
 # as well as any optionally exported functions
 
-@EXPORT_OK   = qw($Var1 %Hashit);
+@EXPORT_OK   = qw($Var1 %Hashit);	# FIXME - These are never used
 
 
 # non-exported package globals go here
-use vars qw(@more $stuff);
+use vars qw(@more $stuff);		# FIXME - These are never used
 
 # initalize package globals, first exported ones
 
+# FIXME - These are never used
 my $Var1   = '';
 my %Hashit = ();
 
 
 # then the others (which are still accessible as $Some::Module::stuff)
+# FIXME - These are never used
 my $stuff  = '';
 my @more   = ();
 
@@ -70,6 +94,9 @@ my @more   = ();
 #
 # Change this value to reflect where you will store your includes
 #
+# FIXME - Since this is used in several places, it ought to be put
+# into a separate file. Better yet, put "use C4::Config;" inside the
+# &import method of any package that requires the config file.
 my %configfile;
 open (KC, "/etc/koha.conf");
 while (<KC>) {
@@ -93,10 +120,31 @@ my $path=$configfile{'includes'};
 
 # make all your functions, whether exported or not;
 
+=item picktemplate
+
+  $template = &picktemplate($includes, $base);
+
+Returns the preferred template for a given page. C<$base> is the
+basename of the script that will generate the page (with the C<.pl>
+extension stripped off), and C<$includes> is the directory in which
+HTML include files are located.
+
+The preferred template is given by the C<template> entry in the
+C<systempreferences> table in the Koha database. If
+C<$includes>F</templates/preferred-template/>C<$base.tmpl> exists,
+C<&picktemplate> returns the preferred template; otherwise, it returns
+the string C<default>.
+
+=cut
+#'
 sub picktemplate {
   my ($includes, $base) = @_;
   my $dbh=C4Connect;
   my $templates;
+  # FIXME - Instead of generating the list of possible templates, and
+  # then querying the database to see if, by chance, one of them has
+  # been selected, wouldn't it be better to query the database first,
+  # and then see whether the selected template file exists?
   opendir (D, "$includes/templates");
   my @dirlist=readdir D;
   foreach (@dirlist) {
@@ -236,10 +284,25 @@ sub startmenu($) {
   return @string;
 }
 
+=item endmenu
+
+  @lines = &endmenu($type);
+  print join("", @lines);
+
+Given a page type, or category, returns a set of lines of HTML which,
+when concatenated, generate the menu at the bottom of the web page.
 
+C<$type> may be one of C<issue>, C<opac>, C<member>, C<acquisitions>,
+C<report>, C<circulation>, or something else, in which case the menu
+will be for the catalog pages.
+
+=cut
+#'
 sub endmenu {
   my ($type) = @_;
   if ( ! defined $type ) { $type=''; }
+  # FIXME - It's bad form to die in a CGI script. It's even worse form
+  # to die without issuing an error message.
   if ($type eq 'issue') {
     open (FILE,"$path/issues-bottom.inc") || die;
   } elsif ($type eq 'opac') {
@@ -364,10 +427,12 @@ sub mkform3 {
       if ($data[0] eq 'radio') {
         $text="<input type=radio name=$keys[$i2] value=$data[1]>$data[1]
 	<input type=radio name=$keys[$i2] value=$data[2]>$data[2]";
-      } 
+      }
+      # FIXME - Is 40 the right size in all cases?
       if ($data[0] eq 'text') {
         $text="<input type=$data[0] name=$keys[$i2] value=\"$data[1]\" size=40>";
       }
+      # FIXME - Is 40x4 the right size in all cases?
       if ($data[0] eq 'textarea') {
         $text="<textarea name=$keys[$i2] cols=40 rows=4>$data[1]</textarea>";
       }
@@ -377,7 +442,7 @@ sub mkform3 {
        	while ($data[$i] ne "") {
 	  my $val = $data[$i+1];
       	  $text = $text."<option value=$data[$i]>$val";
-	  $i = $i+2;
+	  $i = $i+2;		# FIXME - Use $i += 2.
 	}
 	$text=$text."</select>";
       }	
@@ -387,12 +452,15 @@ sub mkform3 {
     $i2++;
   }
   my $temp=join("\n",@order);
+  # FIXME - Use ".=". That's what it's for.
   $string=$string.$temp;
   $string=$string.mktablerow(1,'white','<input type=submit>');
   $string=$string.mktableft;
   $string=$string."</form>";
+  # FIXME - A return statement, while not strictly necessary, would be nice.
 }
 
+# XXX - POD
 sub mkformnotable{
   my ($action,@inputs)=@_;
   my $string="<form action=$action method=post>\n";
@@ -420,6 +488,79 @@ sub mkformnotable{
   $string=$string."</form>";
 }
 
+=item mkform2
+
+  $str = &mkform2($action,
+	$fieldname => "$fieldpos\t$required\t$label\t$fieldtype\t$value0\t$value1\t...",
+	...
+	);
+  print $str;
+
+Takes a set of arguments that define an input form, generates an HTML
+string for the form, and returns the string.
+
+C<$action> is the action for the form, usually the URL of the script
+that will process it.
+
+The remaining arguments define the fields in the form. C<$fieldname>
+is the field's name. This is for the script's benefit, and will not be
+shown to the user.
+
+C<$fieldpos> is an integer; fields will be output in order of
+increasing C<$fieldpos>. This number must be unique: if two fields
+have the same C<$fieldpos>, one will be picked at random, and the
+other will be ignored. See below for special considerations, however.
+
+If C<$required> is the string C<R>, then the field is required, and
+the label will have C< (Req.)> appended.
+
+C<$label> is a string that will appear next to the input field.
+
+C<$fieldtype> specifies the type of the input field. It may be one of
+the following:
+
+=over 4
+
+=item C<hidden>
+
+Generates a hidden field, used to pass data to the script without
+showing it to the user. C<$value0> is its value.
+
+=item C<radio>
+
+Generates a pair of radio buttons, with values C<$value0> and
+C<$value1>. In both cases, C<$value0> and C<$value1> will be shown to
+the user, next to the radio button.
+
+=item C<text>
+
+Generates a one-line text input field. Its size may be specified by
+C<$value0>. The default is 40. The initial text of the field may be
+specified by C<$value1>.
+
+=item C<textarea>
+
+Generates a text input area. C<$value0> may be a string of the form
+"WWWxHHH", in which case the text input area will be WWW columns wide
+and HHH rows tall. The size defaults to 40x4.
+
+The initial text (which, of course, may not contain any tabs) may be
+specified by C<$value1>.
+
+=item C<select>
+
+Generates a list of items, from which the user may choose one. Here,
+C<$value1>, C<$value2>, etc. are a list of key-value pairs. In each
+pair, the key specifies an internal label for a choice, and the value
+specifies the description of the choice that will be shown the user.
+
+If C<$value0> is the same as one of the keys that follows, then the
+corresponding choice will initially be selected.
+
+=back
+
+=cut
+#'
 sub mkform2{
     # FIXME
     # no POD and no tests yet.  Once tests are written,
@@ -639,6 +780,13 @@ sub getkeytableselectoptions {
 #---------------------------------
 
 END { }       # module clean-up code here (global destructor)
-    
 
+1;
+__END__
+=back
+
+=head1 SEE ALSO
+
+L<DBI(3)|DBI>
 
+=cut
diff --git a/C4/Search.pm b/C4/Search.pm
index e06fa560be..1af66f5b8d 100755
--- a/C4/Search.pm
+++ b/C4/Search.pm
@@ -30,14 +30,55 @@ use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
 # set the version for version checking
 $VERSION = 0.02;
     
+=head1 NAME
+
+C4::Search - Functions for searching the Koha catalog and other databases
+
+=head1 SYNOPSIS
+
+  use C4::Search;
+
+  my ($count, @results) = catalogsearch($env, $type, $search, $num, $offset);
+
+=head1 DESCRIPTION
+
+This module provides the searching facilities for the Koha catalog and
+other databases.
+
+C<&catalogsearch> is a front end to all the other searches. Depending
+on what is passed to it, it calls the appropriate search function.
+
+=head1 FUNCTIONS
+
+=over 2
+
+=cut
+
 @ISA = qw(Exporter);
 @EXPORT = qw(&CatSearch &BornameSearch &ItemInfo &KeywordSearch &subsearch
 &itemdata &bibdata &GetItems &borrdata &itemnodata &itemcount
 &borrdata2 &NewBorrowerNumber &bibitemdata &borrissues
 &getboracctrecord &ItemType &itemissues &subject &subtitle
 &addauthor &bibitems &barcodes &findguarantees &allissues &systemprefs
-&findguarantor &getwebsites &getwebbiblioitems &catalogsearch itemcount2);
+&findguarantor &getwebsites &getwebbiblioitems &catalogsearch &itemcount2);
 # make all your functions, whether exported or not;
+
+=item findguarantees
+
+  ($num_children, $children_arrayref) = &findguarantees($parent_borrno);
+  $child0_cardno = $children_arrayref->[0]{"cardnumber"};
+  $child0_borrno = $children_arrayref->[0]{"borrowernumber"};
+
+C<&findguarantees> takes a borrower number (e.g., that of a patron
+with children) and looks up the borrowers who are guaranteed by that
+borrower (i.e., the patron's children).
+
+C<&findguarantees> returns two values: an integer giving the number of
+borrowers guaranteed by C<$parent_borrno>, and a reference to an array
+of references to hash, which gives the actual results.
+
+=cut
+#'
 sub findguarantees{         
   my ($bornum)=@_;         
   my $dbh=C4Connect;           
@@ -55,6 +96,23 @@ sub findguarantees{
   $dbh->disconnect;         
   return($i,\@dat);             
 }
+
+=item findguarantor
+
+  $guarantor = &findguarantor($borrower_no);
+  $guarantor_cardno = $guarantor->{"cardnumber"};
+  $guarantor_surname = $guarantor->{"surname"};
+  ...
+
+C<&findguarantor> takes a borrower number (presumably that of a child
+patron), finds the guarantor for C<$borrower_no> (the child's parent),
+and returns the record for the guarantor.
+
+C<&findguarantor> returns a reference-to-hash. Its keys are the fields
+from the C<borrowers> database table;
+
+=cut
+#'
 sub findguarantor{  
   my ($bornum)=@_;  
   my $dbh=C4Connect;    
@@ -74,6 +132,15 @@ sub findguarantor{
   return($data);            
 }
 
+=item systemprefs
+
+  %prefs = &systemprefs();
+
+Returns a hash giving the system preferences. This is basically just a
+dump of the C<systempreferences> database table.
+
+=cut
+#'
 sub systemprefs {
     my %systemprefs;
     my $dbh=C4Connect;
@@ -87,6 +154,14 @@ sub systemprefs {
     return(%systemprefs);
 }
 
+=item NewBorrowerNumber
+
+  $num = &NewBorrowerNumber();
+
+Allocates a new, unused borrower number, and returns it.
+
+=cut
+#'
 sub NewBorrowerNumber {           
   my $dbh=C4Connect;        
   my $sth=$dbh->prepare("Select max(borrowernumber) from borrowers");     
@@ -98,6 +173,46 @@ sub NewBorrowerNumber {
   return($data->{'max(borrowernumber)'}); 
 }    
 
+=item catalogsearch
+
+  ($count, @results) = &catalogsearch($env, $type, $search, $num, $offset);
+
+This is primarily a front-end to other, more specialized catalog
+search functions: if C<$search-E<gt>{itemnumber}> or
+C<$search-E<gt>{isbn}> is given, C<&catalogsearch> uses a precise
+C<&CatSearch>. If $search->{subject} is given, it runs a subject
+C<&CatSearch>. If C<$search-E<gt>{keyword}> is given, it runs a
+C<&KeywordSearch>. Otherwise, it runs a loose C<&CatSearch>.
+
+If C<$env-E<gt>{itemcount}> is 1, then C<&catalogsearch> also counts
+the items for each result, and adds several keys:
+
+=over 4
+
+=item C<itemcount>
+
+The total number of copies of this book.
+
+=item C<locationhash>
+
+This is a reference-to-hash; the keys are the names of branches where
+this book may be found, and the values are the number of copies at
+that branch.
+
+=item C<location>
+
+A descriptive string saying where the book is located, and how many
+copies there are, if greater than 1.
+
+=item C<subject2>
+
+The book's subject, with spaces replaced with C<%20>, presumably for
+HTML.
+
+=back
+
+=cut
+#'
 sub catalogsearch {
   my ($env,$type,$search,$num,$offset)=@_;
   my $dbh = C4Connect();
@@ -106,6 +221,7 @@ sub catalogsearch {
 #  }
   my ($count,@results);
 #  print STDERR "Doing a search \n";
+  # FIXME - Use "elsif" to avoid this sort of deep nesting
   if ($search->{'itemnumber'} ne '' || $search->{'isbn'} ne ''){
         print STDERR "Doing a precise search\n";
     ($count,@results)=CatSearch($env,'precise',$search,$num,$offset);
@@ -130,7 +246,7 @@ sub catalogsearch {
       $data->{'itemcount'}=$counts->{'total'};
       my $totalitemcounts=0;
       foreach my $key (keys %$counts){
-        if ($key ne 'total'){
+        if ($key ne 'total'){	# FIXME - Should ignore 'order', too.
           #$data->{'location'}.="$key $counts->{$key} ";
 	  $totalitemcounts+=$counts->{$key};
           $data->{'locationhash'}->{$key}=$counts->{$key};
@@ -165,6 +281,52 @@ sub catalogsearch {
   return ($count,@results);
 }
 
+=item KeywordSearch
+
+  $search = { "keyword"	=> "One or more keywords",
+	      "class"	=> "VID|CD",	# Limit search to fiction and CDs
+	      "dewey"	=> "813",
+	 };
+  ($count, @results) = &KeywordSearch($env, $type, $search, $num, $offset);
+
+C<&KeywordSearch> searches the catalog by keyword: given a string
+(C<$search-E<gt>{"keyword"}> consisting of a space-separated list of
+keywords, it looks for books that contain any of those keywords in any
+of a number of places.
+
+C<&KeywordSearch> looks for keywords in the book title (and subtitle),
+series name, notes (both C<biblio.notes> and C<biblioitems.notes>),
+and subjects.
+
+C<$search-E<gt>{"class"}> can be set to a C<|> (pipe)-separated list of
+item class codes (e.g., "F" for fiction, "JNF" for junior nonfiction,
+etc.). In this case, the search will be restricted to just those
+classes.
+
+If C<$search-E<gt>{"class"}> is not specified, you may specify
+C<$search-E<gt>{"dewey"}>. This will restrict the search to that
+particular Dewey Decimal Classification category. Setting
+C<$search-E<gt>{"dewey"}> to "513" will return books about arithmetic,
+whereas setting it to "5" will return all books with Dewey code 5I<xx>
+(Science and Mathematics).
+
+C<$env> and C<$type> are ignored.
+
+C<$offset> and C<$num> specify the subset of results to return.
+C<$num> specifies the number of results to return, and C<$offset> is
+the number of the first result. Thus, setting C<$offset> to 100 and
+C<$num> to 5 will return results 100 through 104 inclusive.
+
+=cut
+#'
+
+# FIXME - Everything that's being done here with Set::Scalar can be
+# done with hashes: to add a result to the set, just use:
+#	$results{$foo} = 1;
+# To get the list of results, just use
+#	@biblionumbers = sort keys %results;
+# This would remove the dependency on Set::Scalar, which means one
+# fewer package that people have to install.
   
 sub KeywordSearch {
   my ($env,$type,$search,$num,$offset)=@_;
@@ -175,6 +337,28 @@ sub KeywordSearch {
   my $count=@key;
   my $i=1;
   my @results;
+
+  # Look for keywords in table 'biblio'.
+
+  # FIXME - The next 15 lines can be rewritten in somewhat Lisp-ish
+  # fashion as follows:
+  #
+  # my $query = "select biblionumber from biblio where (" .
+  #	join(") or (",
+  #	     map {
+  #		     my $field = $_;
+  #		     join (" and ",
+  #			   map {
+  #			     "($field like '$_\%' or $field like '\% $_\%')"
+  #		           }
+  #		           @key)
+  #	     }
+  #	     qw( title biblio.notes seriestitle )) .
+  #	")";
+  # FIXME - Also,
+  #	field like 'string%' or field like '% string%'
+  # can be rewritten (in MySQL, at least) as
+  #	field regexp '(^| )string';
   my $query="Select biblionumber from biblio
   where ((title like '$key[0]%' or title like '% $key[0]%')";
   while ($i < $count){                                                  
@@ -200,6 +384,8 @@ sub KeywordSearch {
   }
   $sth->finish;
   my $set1=Set::Scalar->new(@results);
+
+  # Now look for keywords in the 'bibliosubtitle' table.
   $query="Select biblionumber from bibliosubtitle where
   ((subtitle like '$key[0]%' or subtitle like '% $key[0]%')";                 
   for ($i=1;$i<$count;$i++){   
@@ -219,6 +405,9 @@ sub KeywordSearch {
   if ($i > 0){
     $set1=$set1+$set2;
   }
+
+  # Look for the keywords in the notes for individual items
+  # ('biblioitems.notes')
   $query ="Select biblionumber from biblioitems where
   ((biblioitems.notes like '$key[0]%' or biblioitems.notes like '% $key[0]%')";                                   
   for ($i=1;$i<$count;$i++){                                                  
@@ -238,6 +427,8 @@ sub KeywordSearch {
   if ($i > 0){
     $set1=$set1+$set3;
   }
+
+  # Look for keywords in the 'bibliosubject' table.
   $sth=$dbh->prepare("Select biblionumber from bibliosubject where subject
   like '%$search->{'keyword'}%' group by biblionumber");
   $sth->execute;
@@ -266,7 +457,7 @@ sub KeywordSearch {
       my $query="select * from biblio,biblioitems where 
       biblio.biblionumber='$res[$i2]' and     
       biblio.biblionumber=biblioitems.biblionumber ";         
-      if ($search->{'class'} ne ''){             
+      if ($search->{'class'} ne ''){	# FIXME - Redundant
       my @temp=split(/\|/,$search->{'class'});
       my $count=@temp;                       
       $query.= "and ( itemtype='$temp[0]'";     
@@ -281,6 +472,17 @@ sub KeywordSearch {
        if (my $data2=$sth->fetchrow_hashref){            
          my $dewey= $data2->{'dewey'};                
          my $subclass=$data2->{'subclass'};          
+         # FIXME - This next bit is bogus, because it assumes that the
+         # Dewey code is a floating-point number. It isn't. It's
+         # actually a string that mainly consists of numbers. In
+         # particular, "4" is not a valid Dewey code, although "004"
+         # is ("Data processing; Computer science"). Likewise, zeros
+         # after the decimal are significant ("575" is not the same as
+         # "575.0"; the latter is more specific). And "000" is a
+         # perfectly good Dewey code ("General works; computer
+         # science") and should not be interpreted to mean "this
+         # database entry does not have a Dewey code". That's what
+         # NULL is for.
          $dewey=~s/\.*0*$//;           
          ($dewey == 0) && ($dewey=''); 
          ($dewey) && ($dewey.=" $subclass") ;                                    
@@ -308,11 +510,14 @@ sub KeywordSearch {
      $count=$i;
   
    } else {
+  # $search->{'class'} was not specified
   while ($i2 < $num && $i2 < $count){
     my $query="select * from biblio,biblioitems where
     biblio.biblionumber='$res[$i2+$offset]' and        
     biblio.biblionumber=biblioitems.biblionumber ";
-    if ($search->{'class'} ne ''){
+
+    if ($search->{'class'} ne ''){	# FIXME - Ignored: we already know
+					# that $search->{'class'} eq '';
       my @temp=split(/\|/,$search->{'class'});
       my $count=@temp;
       $query.= "and ( itemtype='$temp[0]'";
@@ -501,11 +706,169 @@ sub KeywordSearch2 {
   return($i,@res2);
 }
 
+=item CatSearch
+
+  ($count, @results) = &CatSearch($env, $type, $search, $num, $offset);
+
+C<&CatSearch> searches the Koha catalog. It returns a list whose first
+element is the number of returned results, and whose subsequent
+elements are the results themselves.
+
+Each returned element is a reference-to-hash. Most of the keys are
+simply the fields from the C<biblio> table in the Koha database, but
+the following keys may also be present:
+
+=over 4
+
+=item C<illustrator>
+
+The book's illustrator.
+
+=item C<publisher>
+
+The publisher.
+
+=back
+
+C<$env> is ignored.
+
+C<$type> may be C<subject>, C<loose>, or C<precise>. This controls the
+high-level behavior of C<&CatSearch>, as described below.
+
+In many cases, the description below says that a certain field in the
+database must match the search string. In these cases, it means that
+the beginning of some word in the field must match the search string.
+Thus, an author search for "sm" will return books whose author is
+"John Smith" or "Mike Smalls", but not "Paul Grossman", since the "sm"
+does not occur at the beginning of a word.
+
+Note that within each search mode, the criteria are and-ed together.
+That is, if you perform a loose search on the author "Jerome" and the
+title "Boat", the search will only return books by Jerome containing
+"Boat" in the title.
+
+It is not possible to cross modes, e.g., set the author to "Asimov"
+and the subject to "Math" in hopes of finding books on math by Asimov.
+
+=head2 Loose search
+
+If C<$type> is set to C<loose>, the following search criteria may be
+used:
+
+=over 4
+
+=item C<$search-E<gt>{author}>
+
+The search string is a space-separated list of words. Each word must
+match either the C<author> or C<additionalauthors> field.
+
+=item C<$search-E<gt>{title}>
+
+Each word in the search string must match the book title. If no author
+is specified, the book subtitle will also be searched.
+
+=item C<$search-E<gt>{abstract}>
+
+Searches for the given search string in the book's abstract.
+
+=item C<$search-E<gt>{'date-before'}>
+
+Searches for books whose copyright date matches the search string.
+That is, setting C<$search-E<gt>{'date-before'}> to "1985" will find
+books written in 1985, and setting it to "198" will find books written
+between 1980 and 1989.
+
+=item C<$search-E<gt>{title}>
+
+Searches by title are also affected by the value of
+C<$search-E<gt>{"ttype"}>; if it is set to C<exact>, then the book
+title, (one of) the series titleZ<>(s), or (one of) the unititleZ<>(s) must
+match the search string exactly (the subtitle is not searched).
+
+If C<$search-E<gt>{"ttype"}> is set to anything other than C<exact>,
+each word in the search string must match the title, subtitle,
+unititle, or series title.
+
+=item C<$search-E<gt>{class}>
+
+Restricts the search to certain item classes. The value of
+C<$search-E<gt>{"class"}> is a | (pipe)-separated list of item types.
+Thus, setting it to "F" restricts the search to fiction, and setting
+it to "CD|CAS" will only look in compact disks and cassettes.
+
+=item C<$search-E<gt>{dewey}>
+
+Searches for books whose Dewey Decimal Classification code matches the
+search string. That is, setting C<$search-E<gt>{"dewey"}> to "5" will
+search for all books in 5I<xx> (Science and mathematics), setting it
+to "54" will search for all books in 54I<x> (Chemistry), and setting
+it to "546" will search for books on inorganic chemistry.
+
+=item C<$search-E<gt>{publisher}>
+
+Searches for books whose publisher contains the search string (unlike
+other search criteria, C<$search-E<gt>{publisher}> is a string, not a
+set of words.
+
+=back
+
+=head2 Subject search
+
+If C<$type> is set to C<subject>, the following search criteria may be
+used:
+
+=over 4
+
+=item C<$search-E<gt>{subject}>
+
+The search string is a space-separated list of words, each of which
+must match the book's subject.
+
+Special case: if C<$search-E<gt>{subject}> is set to C<nz>,
+C<&CatSearch> will search for books whose subject is "New Zealand".
+However, setting C<$search-E<gt>{subject}> to C<"nz football"> will
+search for books on "nz" and "football", not books on "New Zealand"
+and "football".
+
+=back
+
+=head2 Precise search
+
+If C<$type> is set to C<precise>, the following search criteria may be
+used:
+
+=over 4
+
+=item C<$search-E<gt>{item}>
+
+Searches for books whose barcode exactly matches the search string.
+
+=item C<$search-E<gt>{isbn}>
+
+Searches for books whose ISBN exactly matches the search string.
+
+=back
+
+For a loose search, if an author was specified, the results are
+ordered by author and title. If no author was specified, the results
+are ordered by title.
+
+For other (non-loose) searches, if a subject was specified, the
+results are ordered alphabetically by subject.
+
+In all other cases (e.g., loose search by keyword), the results are
+not ordered.
+
+=cut
+#'
 sub CatSearch  {
   my ($env,$type,$search,$num,$offset)=@_;
   my $dbh = &C4Connect;
   my $query = '';
     my @results;
+  # FIXME - Why not just
+  #	$search->{'title'} = quotemeta($search->{'title'})
+  # to escape all questionable characters, not just single-quotes?
   $search->{'title'}=~ s/'/\\'/g;
   $search->{'author'}=~ s/'/\\'/g;
   $search->{'illustrator'}=~ s/'/\\'/g;
@@ -660,6 +1023,17 @@ sub CatSearch  {
       or subject like '%($key[$i])%')";
       $i++;
     }
+
+    # FIXME - Wouldn't it be better to fix the database so that if a
+    # book has a subject "NZ", then it also gets added the subject
+    # "New Zealand"?
+    # This can also be generalized by adding a table of subject
+    # synonyms to the database: just declare "NZ" to be a synonym for
+    # "New Zealand", "SF" a synonym for both "Science fiction" and
+    # "Fantastic fiction", etc.
+
+    # FIXME - This can be rewritten as
+    #	if (lc($search->{"subject"}) eq "nz") {
     if ($search->{'subject'} eq 'NZ' || $search->{'subject'} eq 'nz'){ 
       $query.= " or (subject like 'NEW ZEALAND %' or subject like '% NEW ZEALAND %'
       or subject like '% NEW ZEALAND' or subject like '%(NEW ZEALAND)%' ) ";
@@ -693,6 +1067,8 @@ sub CatSearch  {
 	   $sth->execute;
 	   my $data=$sth->fetchrow_hashref;
 	   my ($dewey, $subclass) = ($data->{'dewey'}, $data->{'subclass'});
+	   # FIXME - The following assumes that the Dewey code is a
+	   # floating-point number. It isn't: it's a string.
 	   $dewey=~s/\.*0*$//;
 	   ($dewey == 0) && ($dewey='');
 	   ($dewey) && ($dewey.=" $subclass");
@@ -785,6 +1161,21 @@ sub updatesearchstats{
   
 }
 
+=item subsearch
+
+  @results = &subsearch($env, $subject);
+
+Searches for books that have a subject that exactly matches
+C<$subject>.
+
+C<&subsearch> returns an array of results. Each element of this array
+is a string, containing the book's title, author, and biblionumber,
+separated by tabs.
+
+C<$env> is ignored.
+
+=cut
+#'
 sub subsearch {
   my ($env,$subject)=@_;
   my $dbh=C4Connect();
@@ -807,7 +1198,52 @@ sub subsearch {
   return(@results);
 }
 
+=item ItemInfo
+
+  @results = &ItemInfo($env, $biblionumber, $type);
+
+Returns information about books with the given biblionumber.
+
+C<$type> may be either C<intra> or anything else. If it is not set to
+C<intra>, then the search will exclude lost, very overdue, and
+withdrawn items.
+
+C<$env> is ignored.
+
+C<&ItemInfo> returns a list of references-to-hash. Each element
+contains a number of keys. Most of them are table items from the
+C<biblio>, C<biblioitems>, C<items>, and C<itemtypes> tables in the
+Koha database. Other keys include:
+
+=over 4
 
+=item C<$data-E<gt>{branchname}>
+
+The name (not the code) of the branch to which the book belongs.
+
+=item C<$data-E<gt>{datelastseen}>
+
+This is simply C<items.datelastseen>, except that while the date is
+stored in YYYY-MM-DD format in the database, here it is converted to
+DD/MM/YYYY format. A NULL date is returned as C<//>.
+
+=item C<$data-E<gt>{datedue}>
+
+=item C<$data-E<gt>{class}>
+
+This is the concatenation of C<biblioitems.classification>, the book's
+Dewey code, and C<biblioitems.subclass>.
+
+=item C<$data-E<gt>{ocount}>
+
+I think this is the number of copies of the book available.
+
+=item C<$data-E<gt>{order}>
+
+If this is set, it is set to C<One Order>.
+
+=cut
+#'
 sub ItemInfo {
     my ($env,$biblionumber,$type) = @_;
     my $dbh   = &C4Connect;
@@ -836,6 +1272,8 @@ sub ItemInfo {
     my $isth=$dbh->prepare($iquery);
     $isth->execute;
     if (my $idata=$isth->fetchrow_hashref){
+      # FIXME - The date ought to be properly parsed, and printed
+      # according to local convention.
       my @temp=split('-',$idata->{'date_due'});
       $datedue = "$temp[2]/$temp[1]/$temp[0]";
     }
@@ -868,7 +1306,8 @@ sub ItemInfo {
     my $class = $data->{'classification'};
     my $dewey = $data->{'dewey'};
     $dewey =~ s/0+$//;
-    if ($dewey eq "000.") { $dewey = "";};    
+    if ($dewey eq "000.") { $dewey = "";};	# FIXME - "000" is general
+						# books about computer science
     if ($dewey < 10){$dewey='00'.$dewey;}
     if ($dewey < 100 && $dewey > 10){$dewey='0'.$dewey;}
     if ($dewey <= 0){
@@ -880,6 +1319,9 @@ sub ItemInfo {
       $class = $class.$data->{'subclass'};
     }
  #   $results[$i]="$data->{'title'}\t$data->{'barcode'}\t$datedue\t$data->{'branchname'}\t$data->{'dewey'}";
+    # FIXME - If $data->{'datelastseen'} is NULL, perhaps it'd be prettier
+    # to leave it empty, rather than convert it to "//".
+    # Also ideally this should use the local format for displaying dates.
     my @temp=split('-',$data->{'datelastseen'});
     my $date="$temp[2]/$temp[1]/$temp[0]";
     $data->{'datelastseen'}=$date;
@@ -908,6 +1350,26 @@ sub ItemInfo {
   return(@results);
 }
 
+=item GetItems
+
+  @results = &GetItems($env, $biblionumber);
+
+Returns information about books with the given biblionumber.
+
+C<$env> is ignored.
+
+C<&GetItems> returns an array of strings. Each element is a
+tab-separated list of values: biblioitemnumber, itemtype,
+classification, Dewey number, subclass, ISBN, volume, number, and
+itemdata.
+
+Itemdata, in turn, is a string of the form
+"I<barcode>C<[>I<holdingbranch>C<[>I<flags>" where I<flags> contains
+the string C<NFL> if the item is not for loan, and C<LOST> if the item
+is lost.
+
+=cut
+#'
 sub GetItems {
    my ($env,$biblionumber)=@_;
    #debug_msg($env,"GetItems");
@@ -948,6 +1410,17 @@ sub GetItems {
    return(@results);
 }	     
   
+=item itemdata
+
+  $item = &itemdata($barcode);
+
+Looks up the item with the given barcode, and returns a
+reference-to-hash containing information about that item. The keys of
+the hash are the fields from the C<items> and C<biblioitems> tables in
+the Koha database.
+
+=cut
+#'
 sub itemdata {
   my ($barcode)=@_;
   my $dbh=C4Connect;
@@ -962,7 +1435,26 @@ sub itemdata {
   return($data);
 }
 
+=item bibdata
+
+  $data = &bibdata($biblionumber, $type);
+
+Returns information about the book with the given biblionumber.
+
+C<$type> is ignored.
+
+C<&bibdata> returns a reference-to-hash. The keys are the fields in
+the C<biblio>, C<biblioitems>, and C<bibliosubtitle> tables in the
+Koha database.
+
+In addition, C<$data-E<gt>{subject}> is the list of the book's
+subjects, separated by C<" , "> (space, comma, space).
+
+If there are multiple biblioitems with the given biblionumber, only
+the first one is considered.
 
+=cut
+#'
 sub bibdata {
     my ($bibnum, $type) = @_;
     my $dbh   = C4Connect;
@@ -991,7 +1483,17 @@ sub bibdata {
     return($data);
 } # sub bibdata
 
+=item bibitemdata
+
+  $itemdata = &bibitemdata($biblioitemnumber);
+
+Looks up the biblioitem with the given biblioitemnumber. Returns a
+reference-to-hash. The keys are the fields from the C<biblio>,
+C<biblioitems>, and C<itemtypes> tables in the Koha database, except
+that C<biblioitems.notes> is given as C<$itemdata-E<gt>{bnotes}>.
 
+=cut
+#'
 sub bibitemdata {
     my ($bibitem) = @_;
     my $dbh   = C4Connect;
@@ -1011,7 +1513,17 @@ and biblioitems.itemtype = itemtypes.itemtype";
     return($data);
 } # sub bibitemdata
 
+=item subject
+
+  ($count, $subjects) = &subject($biblionumber);
 
+Looks up the subjects of the book with the given biblionumber. Returns
+a two-element list. C<$subjects> is a reference-to-array, where each
+element is a subject of the book, and C<$count> is the number of
+elements in C<$subjects>.
+
+=cut
+#'
 sub subject {
   my ($bibnum)=@_;
   my $dbh=C4Connect;
@@ -1029,6 +1541,19 @@ sub subject {
   return($i,\@results);
 }
 
+=item addauthor
+
+  ($count, $authors) = &addauthors($biblionumber);
+
+Looks up the additional authors for the book with the given
+biblionumber.
+
+Returns a two-element list. C<$authors> is a reference-to-array, where
+each element is an additional author, and C<$count> is the number of
+elements in C<$authors>.
+
+=cut
+#'
 sub addauthor {
   my ($bibnum)=@_;
   my $dbh=C4Connect;
@@ -1046,6 +1571,18 @@ sub addauthor {
   return($i,\@results);
 }
 
+=item subtitle
+
+  ($count, $subtitles) = &subtitle($biblionumber);
+
+Looks up the subtitles for the book with the given biblionumber.
+
+Returns a two-element list. C<$subtitles> is a reference-to-array,
+where each element is a subtitle, and C<$count> is the number of
+elements in C<$subtitles>.
+
+=cut
+#'
 sub subtitle {
   my ($bibnum)=@_;
   my $dbh=C4Connect;
@@ -1063,13 +1600,60 @@ sub subtitle {
   return($i,\@results);
 }
 
+=item itemissues
+
+  @issues = &itemissues($biblioitemnumber, $biblio);
+
+Looks up information about who has borrowed the bookZ<>(s) with the
+given biblioitemnumber.
+
+C<$biblio> is ignored.
+
+C<&itemissues> returns an array of references-to-hash. The keys
+include the fields from the C<items> table in the Koha database.
+Additional keys include:
+
+=over 4
+
+=item C<date_due>
+
+If the item is currently on loan, this gives the due date.
+
+If the item is not on loan, then this is either "Available" or
+"Cancelled", if the item has been withdrawn.
+
+=item C<card>
+
+If the item is currently on loan, this gives the card number of the
+patron who currently has the item.
+
+=item C<timestamp0>, C<timestamp1>, C<timestamp2>
+
+These give the timestamp for the last three times the item was
+borrowed.
 
+=item C<card0>, C<card1>, C<card2>
 
+The card number of the last three patrons who borrowed this item.
+
+=item C<borrower0>, C<borrower1>, C<borrower2>
+
+The borrower number of the last three patrons who borrowed this item.
+
+=back
+
+=cut
+#'
 sub itemissues {
     my ($bibitem, $biblio)=@_;
     my $dbh   = C4Connect;
     my $query = "Select * from items where 
 items.biblioitemnumber = '$bibitem'";
+    # FIXME - If this function die()s, the script will abort, and the
+    # user won't get anything; depending on how far the script has
+    # gotten, the user might get a blank page. It would be much better
+    # to at least print an error message. The easiest way to do this
+    # is to set $SIG{__DIE__}.
     my $sth   = $dbh->prepare($query)
       || die $dbh->errstr;
     my $i     = 0;
@@ -1079,6 +1663,13 @@ items.biblioitemnumber = '$bibitem'";
       || die $sth->errstr;
 
     while (my $data = $sth->fetchrow_hashref) {
+        # Find out who currently has this item.
+        # FIXME - Wouldn't it be better to do this as a left join of
+        # some sort? Currently, this code assumes that if
+        # fetchrow_hashref() fails, then the book is on the shelf.
+        # fetchrow_hashref() can fail for any number of reasons (e.g.,
+        # database server crash), not just because no items match the
+        # search criteria.
         my $query2 = "select * from issues,borrowers
 where itemnumber = $data->{'itemnumber'}
 and returndate is NULL
@@ -1098,6 +1689,8 @@ and issues.borrowernumber = borrowers.borrowernumber";
         } # else
 
         $sth2->finish;
+
+        # Find the last 3 people who borrowed this item.
         $query2 = "select * from issues, borrowers
 where itemnumber = '$data->{'itemnumber'}'
 and issues.borrowernumber = borrowers.borrowernumber 
@@ -1126,7 +1719,20 @@ order by returndate desc,timestamp desc";
     return(@results);
 }
 
+=item itemnodata
+
+  $item = &itemnodata($env, $dbh, $biblioitemnumber);
+
+Looks up the item with the given biblioitemnumber.
+
+C<$env> and C<$dbh> are ignored.
+
+C<&itemnodata> returns a reference-to-hash whose keys are the fields
+from the C<biblio>, C<biblioitems>, and C<items> tables in the Koha
+database.
 
+=cut
+#'
 sub itemnodata {
   my ($env,$dbh,$itemnumber) = @_;
   $dbh=C4Connect;
@@ -1143,6 +1749,25 @@ sub itemnodata {
   return($data);	       
 }
 
+=item BornameSearch
+
+  ($count, $borrowers) = &BornameSearch($env, $searchstring, $type);
+
+Looks up patrons (borrowers) by name.
+
+C<$env> and C<$type> are ignored.
+
+C<$searchstring> is a space-separated list of search terms. Each term
+must match the beginning a borrower's surname, first name, or other
+name.
+
+C<&BornameSearch> returns a two-element list. C<$borrowers> is a
+reference-to-array; each element is a reference-to-hash, whose keys
+are the fields of the C<borrowers> table in the Koha database.
+C<$count> is the number of elements in C<$borrowers>.
+
+=cut
+#'
 #used by member enquiries from the intranet
 #called by member.pl
 sub BornameSearch  {
@@ -1178,6 +1803,19 @@ sub BornameSearch  {
   return ($cnt,\@results);
 }
 
+=item borrdata
+
+  $borrower = &borrdata($cardnumber, $borrowernumber);
+
+Looks up information about a patron (borrower) by either card number
+or borrower number. If $borrowernumber is specified, C<&borrdata>
+searches by borrower number; otherwise, it searches by card number.
+
+C<&borrdata> returns a reference-to-hash whose keys are the fields of
+the C<borrowers> table in the Koha database.
+
+=cut
+#'
 sub borrdata {
   my ($cardnumber,$bornum)=@_;
   $cardnumber = uc $cardnumber;
@@ -1197,6 +1835,20 @@ sub borrdata {
   return($data);
 }
 
+=item borrissues
+
+  ($count, $issues) = &borrissues($borrowernumber);
+
+Looks up what the patron with the given borrowernumber has borrowed.
+
+C<&borrissues> returns a two-element array. C<$issues> is a
+reference-to-array, where each element is a reference-to-hash; the
+keys are the fields from the C<issues>, C<biblio>, and C<items> tables
+in the Koha database. C<$count> is the number of elements in
+C<$issues>.
+
+=cut
+#'
 sub borrissues {
   my ($bornum)=@_;
   my $dbh=C4Connect;
@@ -1219,6 +1871,27 @@ by date_due";
   return($i,\@result);
 }
 
+=item allissues
+
+  ($count, $issues) = &allissues($borrowernumber, $sortkey, $limit);
+
+Looks up what the patron with the given borrowernumber has borrowed,
+and sorts the results.
+
+C<$sortkey> is the name of a field on which to sort the results. This
+should be the name of a field in the C<issues>, C<biblio>,
+C<biblioitems>, or C<items> table in the Koha database.
+
+C<$limit> is the maximum number of results to return.
+
+C<&allissues> returns a two-element array. C<$issues> is a
+reference-to-array, where each element is a reference-to-hash; the
+keys are the fields from the C<issues>, C<biblio>, C<biblioitems>, and
+C<items> tables of the Koha database. C<$count> is the number of
+elements in C<$issues>
+
+=cut
+#'
 sub allissues { 
   my ($bornum,$order,$limit)=@_; 
   my $dbh=C4Connect;   
@@ -1246,6 +1919,22 @@ sub allissues {
   return($i,\@result);               
 }
 
+=item borrdata2
+
+  ($borrowed, $due, $fine) = &borrdata2($env, $borrowernumber);
+
+Returns aggregate data about items borrowed by the patron with the
+given borrowernumber.
+
+C<$env> is ignored.
+
+C<&borrdata2> returns a three-element array. C<$borrowed> is the
+number of books the patron currently has borrowed. C<$due> is the
+number of overdue items the patron currently has borrowed. C<$fine> is
+the total fine currently due by the borrower.
+
+=cut
+#'
 sub borrdata2 {
   my ($env,$bornum)=@_;
   my $dbh=C4Connect;
@@ -1271,7 +1960,24 @@ sub borrdata2 {
 return($data2->{'count(*)'},$data->{'count(*)'},$data3->{'sum(amountoutstanding)'});
 }
 	
+=item getboracctrecord
+
+  ($count, $acctlines, $total) = &getboracctrecord($env, $borrowernumber);
+
+Looks up accounting data for the patron with the given borrowernumber.
 
+C<$env> is ignored.
+
+(FIXME - I'm not at all sure what this is about.)
+
+C<&getboracctrecord> returns a three-element array. C<$acctlines> is a
+reference-to-array, where each element is a reference-to-hash; the
+keys are the fields of the C<accountlines> table in the Koha database.
+C<$count> is the number of elements in C<$acctlines>. C<$total> is the
+total amount outstanding for all of the account lines.
+
+=cut
+#'
 sub getboracctrecord {
    my ($env,$params) = @_;
    my $dbh=C4Connect;
@@ -1302,7 +2008,46 @@ borrowernumber=$params->{'borrowernumber'} order by date desc,timestamp desc";
    return ($numlines,\@acctlines,$total);
 }
 
+=item itemcount
+
+  ($count, $lcount, $nacount, $fcount, $scount, $lostcount,
+  $mending, $transit,$ocount) =
+    &itemcount($env, $biblionumber, $type);
+
+Counts the number of items with the given biblionumber, broken down by
+category.
+
+C<$env> is ignored.
+
+If C<$type> is not set to C<intra>, lost, very overdue, and withdrawn
+items will not be counted.
+
+C<&itemcount> returns a nine-element list:
+
+C<$count> is the total number of items with the given biblionumber.
+
+C<$lcount> is the number of items at the Levin branch.
+
+C<$nacount> is the number of items that are neither borrowed, lost,
+nor withdrawn (and are therefore presumably on a shelf somewhere).
+
+C<$fcount> is the number of items at the Foxton branch.
+
+C<$scount> is the number of items at the Shannon branch.
 
+C<$lostcount> is the number of lost and very overdue items.
+
+C<$mending> is the number of items at the Mending branch (being
+mended?).
+
+C<$transit> is the number of items at the Transit branch (in transit
+between branches?).
+
+C<$ocount> is the number of items that haven't arrived yet
+(aqorders.quantity - aqorders.quantityreceived).
+
+=cut
+#'
 sub itemcount { 
   my ($env,$bibnum,$type)=@_; 
   my $dbh=C4Connect;   
@@ -1375,7 +2120,42 @@ sub itemcount {
   return ($count,$lcount,$nacount,$fcount,$scount,$lostcount,$mending,$transit,$ocount); 
 }
 
+=item itemcount2
+
+  $counts = &itemcount2($env, $biblionumber, $type);
+
+Counts the number of items with the given biblionumber, broken down by
+category.
+
+C<$env> is ignored.
+
+C<$type> may be either C<intra> or anything else. If it is not set to
+C<intra>, then the search will exclude lost, very overdue, and
+withdrawn items.
+
+C<$&itemcount2> returns a reference-to-hash, with the following fields:
 
+=over 4
+
+=item C<total>
+
+The total number of items with this biblionumber.
+
+=item C<order>
+
+The number of items on order (aqorders.quantity -
+aqorders.quantityreceived).
+
+=item I<branchname>
+
+For each branch that has at least one copy of the book, C<$counts>
+will have a key with the branch name, giving the number of copies at
+that branch.
+
+=back
+
+=cut
+#'
 sub itemcount2 { 
   my ($env,$bibnum,$type)=@_; 
   my $dbh=C4Connect;   
@@ -1400,6 +2180,9 @@ sub itemcount2 {
     
     my $sth2=$dbh->prepare($query2);     
     $sth2->execute;         
+    # FIXME - fetchrow_hashref() can fail for any number of reasons
+    # (e.g., a database server crash). Perhaps use a left join of some
+    # sort for this?
     if (my $data2=$sth2->fetchrow_hashref){         
        $counts{'not available'}++;         
     } else {         
@@ -1420,7 +2203,35 @@ sub itemcount2 {
   return (\%counts); 
 }
 
+=item ItemType
 
+  $description = &ItemType($itemtype);
+
+Given an item type code, returns the description for that type.
+
+=cut
+#'
+
+# FIXME - I'm pretty sure that after the initial setup, the list of
+# item types doesn't change very often. Hence, it seems slow and
+# inefficient to make yet another database call to look up information
+# that'll only change every few months or years.
+#
+# Much better, I think, to automatically build a Perl file that can be
+# included in those scripts that require it, e.g.:
+#	@itemtypes = qw( ART BCD CAS CD F ... );
+#	%itemtypedesc = (
+#		ART	=> "Art Prints",
+#		BCD	=> "CD-ROM from book",
+#		CD	=> "Compact disc (WN)",
+#		F	=> "Free Fiction",
+#		...
+#	);
+# The web server can then run a cron job to rebuild this file from the
+# database every hour or so.
+#
+# The same thing goes for branches, book funds, book sellers, currency
+# rates, printers, stopwords, and perhaps others.
 sub ItemType {
   my ($type)=@_;
   my $dbh=C4Connect;
@@ -1433,7 +2244,24 @@ sub ItemType {
   return ($dat->{'description'});
 }
 
+=item bibitems
+
+  ($count, @results) = &bibitems($biblionumber);
+
+Given the biblionumber for a book, C<&bibitems> looks up that book's
+biblioitems (different publications of the same book, the audio book
+and film versions, etc.).
+
+C<$count> is the number of elements in C<@results>.
+
+C<@results> is an array of references-to-hash; the keys are the fields
+of the C<biblioitems> and C<itemtypes> tables of the Koha database. In
+addition, C<itemlost> indicates the availability of the item: if it is
+"2", then all copies of the item are long overdue; if it is "1", then
+all copies are lost; otherwise, there is at least one copy available.
 
+=cut
+#'
 sub bibitems {
     my ($bibnum) = @_;
     my $dbh   = C4Connect;
@@ -1459,6 +2287,19 @@ sub bibitems {
     return($count, @results);
 } # sub bibitems
 
+=item barcodes
+
+  @barcodes = &barcodes($biblioitemnumber);
+
+Given a biblioitemnumber, looks up the corresponding items.
+
+Returns an array of references-to-hash; the keys are C<barcode> and
+C<itemlost>.
+
+The returned items include very overdue items, but not lost ones.
+
+=cut
+#'
 sub barcodes{
     #called from request.pl
     my ($biblioitemnumber)=@_;
@@ -1479,7 +2320,20 @@ sub barcodes{
     return(@barcodes);
 }
 
+=item getwebsites
+
+  ($count, @websites) = &getwebsites($biblionumber);
+
+Looks up the web sites pertaining to the book with the given
+biblionumber.
 
+C<$count> is the number of elements in C<@websites>.
+
+C<@websites> is an array of references-to-hash; the keys are the
+fields from the C<websites> table in the Koha database.
+
+=cut
+#'
 sub getwebsites {
     my ($biblionumber) = @_;
     my $dbh   = C4Connect;
@@ -1490,7 +2344,13 @@ sub getwebsites {
 
     $sth->execute;
     while (my $data = $sth->fetchrow_hashref) {
-        $data->{'url'} =~ s/^http:\/\///;
+        # FIXME - The URL scheme shouldn't be stripped off, at least
+        # not here, since it's part of the URL, and will be useful in
+        # constructing a link to the site. If you don't want the user
+        # to see the "http://" part, strip that off when building the
+        # HTML code.
+        $data->{'url'} =~ s/^http:\/\///;	# FIXME - Leaning toothpick
+						# syndrome
         $results[$count] = $data;
     	$count++;
     } # while
@@ -1500,7 +2360,19 @@ sub getwebsites {
     return($count, @results);
 } # sub getwebsites
 
+=item getwebbiblioitems
+
+  ($count, @results) = &getwebbiblioitems($biblionumber);
 
+Given a book's biblionumber, looks up the web versions of the book
+(biblioitems with itemtype C<WEB>).
+
+C<$count> is the number of items in C<@results>. C<@results> is an
+array of references-to-hash; the keys are the items from the
+C<biblioitems> table of the Koha database.
+
+=cut
+#'
 sub getwebbiblioitems {
     my ($biblionumber) = @_;
     my $dbh   = C4Connect;
@@ -1525,27 +2397,10 @@ and itemtype = 'WEB'";
 
 END { }       # module clean-up code here (global destructor)
 
-=head1 NAME
-
-C4::Search - Module that provides Catalog searching for Koha
-
-=head1 SYNOPSIS
-
-  use C4::Search;
-  my ($count,@results)=catalogsearch($env,$type,$search,$num,$offset);
-
-=head1 DESCRIPTION
-
-This module provides the searching facilities for the Catalog.
-Here I should go through and document each function thats exported and what it does. But I havent yet.
-
-my ($count,@results)=catalogsearch($env,$type,$search,$num,$offset);
-This is a front end to all the other searches, depending on what is passed
-to it, it calls the appropriate search
-
-=head2 EXPORT
+1;
+__END__
 
-catalogsearch
+=back
 
 =head1 AUTHOR
 
-- 
2.39.5