From: Jared Camins-Esakov <jcamins@cpbibliography.com>
Date: Sun, 9 Sep 2012 14:52:06 +0000 (-0400)
Subject: Start adding skeletal POD for subroutines
X-Git-Url: https://old-git.evergreen-ils.org/?a=commitdiff_plain;h=28b60feaae17822cf7f3d39506cd48423bcc74d6;p=working%2FEvergreen.git

Start adding skeletal POD for subroutines

Signed-off-by: Jared Camins-Esakov <jcamins@cpbibliography.com>
---

diff --git a/Open-ILS/src/perlmods/lib/OpenILS/Application/Storage/QueryParser.pm b/Open-ILS/src/perlmods/lib/OpenILS/Application/Storage/QueryParser.pm
index abc06ad3be..f5e86739f4 100644
--- a/Open-ILS/src/perlmods/lib/OpenILS/Application/Storage/QueryParser.pm
+++ b/Open-ILS/src/perlmods/lib/OpenILS/Application/Storage/QueryParser.pm
@@ -3,6 +3,23 @@ use warnings;
 
 package QueryParser;
 use OpenSRF::Utils::JSON;
+=head1 NAME
+
+QueryParser - basic QueryParser class
+
+=head1 SYNOPSIS
+
+use QueryParser;
+my $QParser = QueryParser->new(%args);
+
+=head1 DESCRIPTION
+
+Main entrypoint into the QueryParser functionality.
+
+=head1 FUNCTIONS
+
+=cut
+
 # Note that the first key must match the name of the package.
 our %parser_config = (
     QueryParser => {
@@ -20,26 +37,52 @@ our %parser_config = (
     }
 );
 
+
+=head2 facet_class_count
+
+    $count = $QParser->facet_class_count();
+=cut
+
 sub facet_class_count {
     my $self = shift;
     return @{$self->facet_classes};
 }
 
+=head2 search_class_count
+
+    $count = $QParser->search_class_count();
+=cut
+
 sub search_class_count {
     my $self = shift;
     return @{$self->search_classes};
 }
 
+=head2 filter_count
+
+    $count = $QParser->filter_count();
+=cut
+
 sub filter_count {
     my $self = shift;
     return @{$self->filters};
 }
 
+=head2 modifier_count
+
+    $count = $QParser->modifier_count();
+=cut
+
 sub modifier_count {
     my $self = shift;
     return @{$self->modifiers};
 }
 
+=head2 custom_data
+
+    $data = $QParser->custom_data($class);
+=cut
+
 sub custom_data {
     my $class = shift;
     $class = ref($class) || $class;
@@ -48,6 +91,13 @@ sub custom_data {
     return $parser_config{$class}{custom_data};
 }
 
+=head2 operators
+
+    $operators = $QParser->operators();
+
+Returns hashref of the configured operators.
+=cut
+
 sub operators {
     my $class = shift;
     $class = ref($class) || $class;
@@ -56,6 +106,13 @@ sub operators {
     return $parser_config{$class}{operators};
 }
 
+=head2 filters
+
+    $filters = $QParser->filters();
+
+Returns arrayref of the configured filters.
+=cut
+
 sub filters {
     my $class = shift;
     $class = ref($class) || $class;
@@ -64,6 +121,13 @@ sub filters {
     return $parser_config{$class}{filters};
 }
 
+=head2 filter_callbacks
+
+    $filter_callbacks = $QParser->filter_callbacks();
+
+Returns hashref of the configured filter callbacks.
+=cut
+
 sub filter_callbacks {
     my $class = shift;
     $class = ref($class) || $class;
@@ -72,6 +136,13 @@ sub filter_callbacks {
     return $parser_config{$class}{filter_callbacks};
 }
 
+=head2 modifiers
+
+    $modifiers = $QParser->modifiers();
+
+Returns arrayref of the configured modifiers.
+=cut
+
 sub modifiers {
     my $class = shift;
     $class = ref($class) || $class;
@@ -80,6 +151,13 @@ sub modifiers {
     return $parser_config{$class}{modifiers};
 }
 
+=head2 new
+
+    $QParser = QueryParser->new(%args);
+
+Creates a new QueryParser object.
+=cut
+
 sub new {
     my $class = shift;
     $class = ref($class) || $class;
@@ -99,12 +177,27 @@ sub new {
     return $self;
 }
 
+=head2 new_plan
+
+    $query_plan = $QParser->new_plan();
+
+Create a new query plan.
+=cut
+
 sub new_plan {
     my $self = shift;
     my $pkg = ref($self) || $self;
     return do{$pkg.'::query_plan'}->new( QueryParser => $self, @_ );
 }
 
+=head2 add_search_filter
+
+    $QParser->add_search_filter($filter, [$callback]);
+
+Adds a filter with the specified name and an optional callback to the
+QueryParser configuration.
+=cut
+
 sub add_search_filter {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -117,6 +210,13 @@ sub add_search_filter {
     return $filter;
 }
 
+=head2 add_search_modifier
+
+    $QParser->add_search_modifier($modifier);
+
+Adds a modifier with the specified name to the QueryParser configuration.
+=cut
+
 sub add_search_modifier {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -127,6 +227,13 @@ sub add_search_modifier {
     return $modifier;
 }
 
+=head2 add_facet_class
+
+    $QParser->add_facet_class($facet_class);
+
+Adds a facet class with the specified name to the QueryParser configuration.
+=cut
+
 sub add_facet_class {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -140,6 +247,13 @@ sub add_facet_class {
     return $class;
 }
 
+=head2 add_search_class
+
+    $QParser->add_search_class($class);
+
+Adds a search class with the specified name to the QueryParser configuration.
+=cut
+
 sub add_search_class {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -154,6 +268,33 @@ sub add_search_class {
     return $class;
 }
 
+=head2 add_search_modifier
+
+    $op = $QParser->operator($operator, [$newvalue]);
+
+Retrieves or sets value for the specified operator. Valid operators and
+their defaults are as follows:
+
+=over 4
+
+=item * and => &&
+
+=item * or => ||
+
+=item * group_start => (
+
+=item * group_end => )
+
+=item * required => +
+
+=item * disallowed => -
+
+=item * modifier => #
+
+=back
+
+=cut
+
 sub operator {
     my $class = shift;
     $class = ref($class) || $class;
@@ -168,6 +309,14 @@ sub operator {
     return $parser_config{$class}{operators}{$opname};
 }
 
+=head2 facet_classes
+
+    $classes = $QParser->facet_classes([\@newclasses]);
+
+Returns arrayref of all configured facet classes after optionally
+replacing configuration.
+=cut
+
 sub facet_classes {
     my $class = shift;
     $class = ref($class) || $class;
@@ -178,6 +327,14 @@ sub facet_classes {
     return $parser_config{$class}{facet_classes};
 }
 
+=head2 search_classes
+
+    $classes = $QParser->search_classes([\@newclasses]);
+
+Returns arrayref of all configured search classes after optionally
+replacing the previous configuration.
+=cut
+
 sub search_classes {
     my $class = shift;
     $class = ref($class) || $class;
@@ -188,6 +345,12 @@ sub search_classes {
     return $parser_config{$class}{classes};
 }
 
+=head2 add_query_normalizer
+
+    $function = $QParser->add_query_normalizer($class, $field, $func, [\@params]);
+
+=cut
+
 sub add_query_normalizer {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -207,6 +370,14 @@ sub add_query_normalizer {
     return $func;
 }
 
+=head2 query_normalizers
+
+    $normalizers = $QParser->query_normalizers($class, $field);
+
+Returns a list of normalizers associated with the specified search class
+and field
+=cut
+
 sub query_normalizers {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -227,6 +398,13 @@ sub query_normalizers {
     return $parser_config{$pkg}{normalizers};
 }
 
+=head2 add_filter_normalizer
+
+    $normalizer = $QParser->add_filter_normalizer($filter, $func, [\@params]);
+
+Adds a normalizer function to the specified filter.
+=cut
+
 sub add_filter_normalizer {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -241,6 +419,13 @@ sub add_filter_normalizer {
     return $func;
 }
 
+=head2 filter_normalizers
+
+    $normalizers = $QParser->filter_normalizers($filter);
+
+Return arrayref of normalizer functions associated with the specified filter.
+=cut
+
 sub filter_normalizers {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -256,6 +441,13 @@ sub filter_normalizers {
     return $parser_config{$pkg}{filter_normalizers};
 }
 
+=head2 default_search_class
+
+    $default_class = $QParser->default_search_class([$class]);
+
+Set or return the default search class.
+=cut
+
 sub default_search_class {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -265,6 +457,13 @@ sub default_search_class {
     return $QueryParser::parser_config{$pkg}{default_class};
 }
 
+=head2 remove_facet_class
+
+    $QParser->remove_facet_class($class);
+
+Remove the specified facet class from the configuration.
+=cut
+
 sub remove_facet_class {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -278,6 +477,13 @@ sub remove_facet_class {
     return $class;
 }
 
+=head2 remove_search_class
+
+    $QParser->remove_search_class($class);
+
+Remove the specified search class from the configuration.
+=cut
+
 sub remove_search_class {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -291,6 +497,14 @@ sub remove_search_class {
     return $class;
 }
 
+=head2 add_facet_field
+
+    $QParser->add_facet_field($class, $field);
+
+Adds the specified field (and facet class if it doesn't already exist)
+to the configuration.
+=cut
+
 sub add_facet_field {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -306,6 +520,13 @@ sub add_facet_field {
     return { $class => $field };
 }
 
+=head2 facet_fields
+
+    $fields = $QParser->facet_fields($class);
+
+Returns arrayref with list of fields for specified facet class.
+=cut
+
 sub facet_fields {
     my $class = shift;
     $class = ref($class) || $class;
@@ -314,6 +535,14 @@ sub facet_fields {
     return $parser_config{$class}{facet_fields};
 }
 
+=head2 add_search_field
+
+    $QParser->add_search_field($class, $field);
+
+Adds the specified field (and facet class if it doesn't already exist)
+to the configuration.
+=cut
+
 sub add_search_field {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -329,6 +558,13 @@ sub add_search_field {
     return { $class => $field };
 }
 
+=head2 search_fields
+
+    $fields = $QParser->search_fields();
+
+Returns arrayref with list of configured search fields.
+=cut
+
 sub search_fields {
     my $class = shift;
     $class = ref($class) || $class;
@@ -337,6 +573,11 @@ sub search_fields {
     return $parser_config{$class}{fields};
 }
 
+=head2 add_search_class_alias
+
+    $QParser->add_search_class_alias($class, $alias);
+=cut
+
 sub add_search_class_alias {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -352,6 +593,11 @@ sub add_search_class_alias {
     return { $class => $alias };
 }
 
+=head2 search_class_aliases
+
+    $aliases = $QParser->search_class_aliases($class);
+=cut
+
 sub search_class_aliases {
     my $class = shift;
     $class = ref($class) || $class;
@@ -360,6 +606,11 @@ sub search_class_aliases {
     return $parser_config{$class}{class_map};
 }
 
+=head2 add_search_field_alias
+
+    $QParser->add_search_field_alias($class, $field, $alias);
+=cut
+
 sub add_search_field_alias {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -374,6 +625,11 @@ sub add_search_field_alias {
     return { $class => { $field => $alias } };
 }
 
+=head2 search_field_aliases
+
+    $aliases = $QParser->search_field_aliases();
+=cut
+
 sub search_field_aliases {
     my $class = shift;
     $class = ref($class) || $class;
@@ -382,6 +638,11 @@ sub search_field_aliases {
     return $parser_config{$class}{field_alias_map};
 }
 
+=head2 remove_facet_field
+
+    $QParser->remove_facet_field($class, $field);
+=cut
+
 sub remove_facet_field {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -395,6 +656,11 @@ sub remove_facet_field {
     return { $class => $field };
 }
 
+=head2 remove_search_field
+
+    $QParser->remove_search_field($class, $field);
+=cut
+
 sub remove_search_field {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -408,6 +674,11 @@ sub remove_search_field {
     return { $class => $field };
 }
 
+=head2 remove_search_field_alias
+
+    $QParser->remove_search_field_alias($class, $field, $alias);
+=cut
+
 sub remove_search_field_alias {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -422,6 +693,11 @@ sub remove_search_field_alias {
     return { $class => { $field => $alias } };
 }
 
+=head2 remove_search_class_alias
+
+    $QParser->remove_search_class_alias($class, $alias);
+=cut
+
 sub remove_search_class_alias {
     my $pkg = shift;
     $pkg = ref($pkg) || $pkg;
@@ -435,6 +711,13 @@ sub remove_search_class_alias {
     return { $class => $alias };
 }
 
+=head2 debug
+
+    $debug = $QParser->debug([$debug]);
+
+Return or set whether debugging output is enabled.
+=cut
+
 sub debug {
     my $self = shift;
     my $q = shift;
@@ -442,6 +725,13 @@ sub debug {
     return $self->{_debug};
 }
 
+=head2 query
+
+    $query = $QParser->query([$query]);
+
+Return or set the query.
+=cut
+
 sub query {
     my $self = shift;
     my $q = shift;
@@ -449,6 +739,13 @@ sub query {
     return $self->{_query};
 }
 
+=head2 parse_tree
+
+    $parse_tree = $QParser->parse_tree([$parse_tree]);
+
+Return or set the parse tree associated with the QueryParser.
+=cut
+
 sub parse_tree {
     my $self = shift;
     my $q = shift;
@@ -456,6 +753,14 @@ sub parse_tree {
     return $self->{_parse_tree};
 }
 
+=head2 parse
+
+    $QParser->parse([$query]);
+
+Parse the specified query, or the query already associated with the QueryParser
+object.
+=cut
+
 sub parse {
     my $self = shift;
     my $pkg = ref($self) || $self;
@@ -469,6 +774,15 @@ sub parse {
     return $self;
 }
 
+=head2 decompose
+
+    ($struct, $remainder) = $QParser->decompose($querystring, [$current_class], [$recursing], [$phrase_helper]);
+
+This routine does the heavy work of parsing the query string recursively.
+Returns the top level query plan, or the query plan from a lower level plus
+the portion of the query string that needs to be processed at a higher level.
+=cut
+
 sub decompose {
     my $self = shift;
     my $pkg = ref($self) || $self;
@@ -790,6 +1104,11 @@ sub decompose {
     return ($struct, $remainder);
 }
 
+=head2 find_class_index
+
+    $index = $QParser->find_class_index($class, $query);
+=cut
+
 sub find_class_index {
     my $class = shift;
     my $query = shift;
@@ -806,6 +1125,13 @@ sub find_class_index {
     return -1;
 }
 
+=head2 core_limit
+
+    $limit = $QParser->core_limit([$limit]);
+
+Return and/or set the core_limit.
+=cut
+
 sub core_limit {
     my $self = shift;
     my $l = shift;
@@ -813,6 +1139,13 @@ sub core_limit {
     return $self->{core_limit};
 }
 
+=head2 superpage
+
+    $superpage = $QParser->superpage([$superpage]);
+
+Return and/or set the superpage.
+=cut
+
 sub superpage {
     my $self = shift;
     my $l = shift;
@@ -820,6 +1153,13 @@ sub superpage {
     return $self->{superpage};
 }
 
+=head2 superpage_size
+
+    $size = $QParser->superpage_size([$size]);
+
+Return and/or set the superpage size.
+=cut
+
 sub superpage_size {
     my $self = shift;
     my $l = shift;