diff options
author | mkanat%kerio.com <> | 2005-03-16 11:30:00 +0100 |
---|---|---|
committer | mkanat%kerio.com <> | 2005-03-16 11:30:00 +0100 |
commit | a1389f26c4d580113989711c9638f5f88113b72f (patch) | |
tree | 531f97c358681e42619e953e88fe00a5306651a2 /Bugzilla | |
parent | b99cbd1d893ff0a730ab7187f409bcdf3c6f4aeb (diff) | |
download | bugzilla-a1389f26c4d580113989711c9638f5f88113b72f.tar.gz bugzilla-a1389f26c4d580113989711c9638f5f88113b72f.tar.xz |
Bug 283231: POD for Bugzilla::FlagType
Patch By Kevin Benton <kevin.benton@amd.com> r=mkanat, a=myk
Diffstat (limited to 'Bugzilla')
-rw-r--r-- | Bugzilla/FlagType.pm | 263 |
1 files changed, 225 insertions, 38 deletions
diff --git a/Bugzilla/FlagType.pm b/Bugzilla/FlagType.pm index 8a6eb0272..cf8b5d0f3 100644 --- a/Bugzilla/FlagType.pm +++ b/Bugzilla/FlagType.pm @@ -19,9 +19,39 @@ # # Contributor(s): Myk Melez <myk@mozilla.org> -################################################################################ +=head1 NAME + +Bugzilla::FlagType - A module to deal with Bugzilla flag types. + +=head1 SYNOPSIS + +FlagType.pm provides an interface to flag types as stored in Bugzilla. +See below for more information. + +=head1 NOTES + +=over + +=item * + +Prior to calling routines in this module, it's assumed that you have +already done a C<require CGI.pl>. This will eventually change in a +future version when CGI.pl is removed. + +=item * + +Use of private functions/variables outside this module may lead to +unexpected results after an upgrade. Please avoid using private +functions in other files/modules. Private functions are functions +whose names start with _ or are specifically noted as being private. + +=back + +=cut + +###################################################################### # Module Initialization -################################################################################ +###################################################################### # Make it harder for us to do dangerous things in Perl. use strict; @@ -36,14 +66,24 @@ use Bugzilla::Error; use Bugzilla::Util; use Bugzilla::Config; -# Note! This module requires that its caller have said "require CGI.pl" -# to import relevant functions from that script and its companion globals.pl. - -################################################################################ +###################################################################### # Global Variables -################################################################################ +###################################################################### -# basic sets of columns and tables for getting flag types from the database +=begin private + +=head1 PRIVATE VARIABLES/CONSTANTS + +=over + +=item C<@base_columns> + +basic sets of columns and tables for getting flag types from the +database. B<Used by get, match, sqlify_criteria and perlify_record> + +=back + +=cut my @base_columns = ("1", "flagtypes.id", "flagtypes.name", "flagtypes.description", @@ -52,20 +92,44 @@ my @base_columns = "flagtypes.is_requesteeble", "flagtypes.is_multiplicable", "flagtypes.grant_group_id", "flagtypes.request_group_id"); -# Note: when adding tables to @base_tables, make sure to include the separator -# (i.e. a comma or words like "LEFT OUTER JOIN") before the table name, -# since tables take multiple separators based on the join type, and therefore -# it is not possible to join them later using a single known separator. +=pod + +=over + +=item C<@base_tables> + +Which database(s) is the data coming from? + +Note: when adding tables to @base_tables, make sure to include the separator +(i.e. a comma or words like C<LEFT OUTER JOIN>) before the table name, +since tables take multiple separators based on the join type, and therefore +it is not possible to join them later using a single known separator. +B<Used by get, match, sqlify_criteria and perlify_record> + +=back + +=end private + +=cut my @base_tables = ("flagtypes"); -################################################################################ +###################################################################### # Public Functions -################################################################################ +###################################################################### +=head1 PUBLIC FUNCTIONS/METHODS -sub get { - # Returns a hash of information about a flag type. +=over + +=item C<get($id)> + +Returns a hash of information about a flag type. + +=back +=cut + +sub get { my ($id) = @_; my $select_clause = "SELECT " . join(", ", @base_columns); @@ -80,16 +144,52 @@ sub get { return $type; } +=pod + +=over + +=item C<get_inclusions($id)> + +Someone please document this + +=back + +=cut + sub get_inclusions { my ($id) = @_; return get_clusions($id, "in"); } +=pod + +=over + +=item C<get_exclusions($id)> + +Someone please document this + +=back + +=cut + sub get_exclusions { my ($id) = @_; return get_clusions($id, "ex"); } +=pod + +=over + +=item C<get_clusions($id, $type)> + +Someone please document this + +=back + +=cut + sub get_clusions { my ($id, $type) = @_; @@ -111,10 +211,20 @@ sub get_clusions { return \@clusions; } -sub match { - # Queries the database for flag types matching the given criteria - # and returns the set of matching types. +=pod +=over + +=item C<match($criteria, $include_count)> + +Queries the database for flag types matching the given criteria +and returns the set of matching types. + +=back + +=cut + +sub match { my ($criteria, $include_count) = @_; my @tables = @base_tables; @@ -157,9 +267,19 @@ sub match { return \@types; } +=pod + +=over + +=item C<count($criteria)> + +Returns the total number of flag types matching the given criteria. + +=back + +=cut + sub count { - # Returns the total number of flag types matching the given criteria. - my ($criteria) = @_; # Generate query components. @@ -184,14 +304,25 @@ sub count { return $count; } +=pod + +=over + +=item C<validate($data, $bug_id, $attach_id)> + +Get a list of flag types to validate. Uses the "map" function +to extract flag type IDs from form field names by matching columns +whose name looks like "flag_type-nnn", where "nnn" is the ID, +and returning just the ID portion of matching field names. + +=back + +=cut + sub validate { my $user = Bugzilla->user; my ($data, $bug_id, $attach_id) = @_; - # Get a list of flag types to validate. Uses the "map" function - # to extract flag type IDs from form field names by matching columns - # whose name looks like "flag_type-nnn", where "nnn" is the ID, - # and returning just the ID portion of matching field names. my @ids = map(/^flag_type-(\d+)$/ ? $1 : (), keys %$data); foreach my $id (@ids) @@ -273,10 +404,20 @@ sub validate { } } +=pod + +=over + +=item C<normalize(@ids)> + +Given a list of flag types, checks its flags to make sure they should +still exist after a change to the inclusions/exclusions lists. + +=back + +=cut + sub normalize { - # Given a list of flag types, checks its flags to make sure they should - # still exist after a change to the inclusions/exclusions lists. - # A list of IDs of flag types to normalize. my (@ids) = @_; @@ -309,17 +450,30 @@ sub normalize { Bugzilla::Flag::clear(&::FetchOneColumn()) while &::MoreSQLData(); } -################################################################################ +###################################################################### # Private Functions -################################################################################ +###################################################################### + +=begin private + +=head1 PRIVATE FUNCTIONS + +=over + +=item C<sqlify_criteria($criteria, Rtables, $columns, $having)> + +Converts a hash of criteria into a list of SQL criteria. +$criteria is a reference to the criteria (field => value), +$tables is a reference to an array of tables being accessed +by the query, $columns is a reference to an array of columns +being returned by the query, and $having is a reference to +a criterion to put into the HAVING clause. + +=back + +=cut sub sqlify_criteria { - # Converts a hash of criteria into a list of SQL criteria. - # $criteria is a reference to the criteria (field => value), - # $tables is a reference to an array of tables being accessed - # by the query, $columns is a reference to an array of columns - # being returned by the query, and $having is a reference to - # a criterion to put into the HAVING clause. my ($criteria, $tables, $columns, $having) = @_; # the generated list of SQL criteria; "1=1" is a clever way of making sure @@ -379,9 +533,20 @@ sub sqlify_criteria { return @criteria; } +=pod + +=over + +=item C<perlify_record()> + +Converts data retrieved from the database into a Perl record. Depends on the +formatting as described in @base_columns. + +=back + +=cut + sub perlify_record { - # Converts data retrieved from the database into a Perl record. - my $type = {}; $type->{'exists'} = $_[0]; @@ -402,4 +567,26 @@ sub perlify_record { return $type; } +=end private + +=head1 SEE ALSO + +=over + +=item B<Bugzilla::Flags> + +=back + +=head1 CONTRIBUTORS + +=over + +=item Myk Melez <myk@mozilla.org> + +=item Kevin Benton <kevin.benton@amd.com> + +=back + +=cut + 1; |