[Tools] testbot/doc: Flesh out the perlpod documentation.
Francois Gouget
fgouget at codeweavers.com
Mon Sep 3 17:11:08 CDT 2012
Also fix many documentation copy/paste issues.
---
testbot/bin/WinePatchesHandler.pl | 4 +-
testbot/lib/ObjectModel/BackEnd.pm | 11 +--
testbot/lib/ObjectModel/BasicPropertyDescriptor.pm | 9 +-
testbot/lib/ObjectModel/Collection.pm | 17 +++-
testbot/lib/ObjectModel/DBIBackEnd.pm | 10 ++
.../lib/ObjectModel/DetailrefPropertyDescriptor.pm | 8 +-
testbot/lib/ObjectModel/EnumPropertyDescriptor.pm | 12 ++-
testbot/lib/ObjectModel/Item.pm | 6 +-
.../lib/ObjectModel/ItemrefPropertyDescriptor.pm | 8 +-
testbot/lib/ObjectModel/PropertyDescriptor.pm | 13 ++-
testbot/lib/WineTestBot/Branches.pm | 15 ++-
testbot/lib/WineTestBot/Config.pm | 8 +-
testbot/lib/WineTestBot/Jobs.pm | 70 +++++++++++++-
testbot/lib/WineTestBot/Log.pm | 6 +-
testbot/lib/WineTestBot/Patches.pm | 63 ++++++++++++-
testbot/lib/WineTestBot/PendingPatchSets.pm | 97 +++++++++++++++++++-
testbot/lib/WineTestBot/PendingPatches.pm | 20 +++-
testbot/lib/WineTestBot/Roles.pm | 18 +++-
testbot/lib/WineTestBot/Steps.pm | 20 +++-
testbot/lib/WineTestBot/StepsTasks.pm | 20 +++-
testbot/lib/WineTestBot/Tasks.pm | 36 +++++++-
testbot/lib/WineTestBot/UserRoles.pm | 14 ++-
testbot/lib/WineTestBot/Users.pm | 14 ++-
testbot/lib/WineTestBot/Utils.pm | 6 +-
testbot/lib/WineTestBot/WineTestBotObjects.pm | 15 ++-
25 files changed, 411 insertions(+), 109 deletions(-)
diff --git a/testbot/bin/WinePatchesHandler.pl b/testbot/bin/WinePatchesHandler.pl
index 04a9829..f2b809e 100755
--- a/testbot/bin/WinePatchesHandler.pl
+++ b/testbot/bin/WinePatchesHandler.pl
@@ -1,6 +1,8 @@
#!/usr/bin/perl -Tw
#
-# Tell the engine to expect a winetest.exe update on test.winehq.org
+# This script expects to receive a wine-patches email on stdin and submits it
+# to WineTestBot for testing. It is meant to be called from a tool such as
+# procmail.
#
# Copyright 2009 Ge van Geldorp
#
diff --git a/testbot/lib/ObjectModel/BackEnd.pm b/testbot/lib/ObjectModel/BackEnd.pm
index 54293a9..cf7439e 100644
--- a/testbot/lib/ObjectModel/BackEnd.pm
+++ b/testbot/lib/ObjectModel/BackEnd.pm
@@ -1,5 +1,3 @@
-# Base class for data storage back ends
-#
# Copyright 2009 Ge van Geldorp
#
# This library is free software; you can redistribute it and/or
@@ -18,18 +16,19 @@
use strict;
+package ObjectModel::BackEnd;
+
=head1 NAME
ObjectModel::BackEnd - Base class for data storage back ends
-=head1 SYNOPSIS
+=head1 DESCRIPTION
-=head2 NOTES
+See ObjectModel::DBIBackEnd for the list of methods that actual implementations
+should provide.
=cut
-package ObjectModel::BackEnd;
-
use vars qw(@ISA @EXPORT %ActiveBackEnds);
require Exporter;
diff --git a/testbot/lib/ObjectModel/BasicPropertyDescriptor.pm b/testbot/lib/ObjectModel/BasicPropertyDescriptor.pm
index 04dcea4..2e83b60 100644
--- a/testbot/lib/ObjectModel/BasicPropertyDescriptor.pm
+++ b/testbot/lib/ObjectModel/BasicPropertyDescriptor.pm
@@ -1,6 +1,5 @@
-# Item property description
-#
# Copyright 2009 Ge van Geldorp
+# Copyright 2012 Francois Gouget
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
@@ -20,7 +19,11 @@ use strict;
=head1 NAME
-ObjectModel::PropertyDescriptor - Base class for item property descriptions
+ObjectModel::BasicPropertyDescriptor - Defines a basic property
+
+=head1 DESCRIPTION
+
+This handles the boolean, a number and string columns.
=cut
diff --git a/testbot/lib/ObjectModel/Collection.pm b/testbot/lib/ObjectModel/Collection.pm
index f4755c3..9ca2503 100644
--- a/testbot/lib/ObjectModel/Collection.pm
+++ b/testbot/lib/ObjectModel/Collection.pm
@@ -1,5 +1,3 @@
-# Collection of items
-#
# Copyright 2009 Ge van Geldorp
#
# This library is free software; you can redistribute it and/or
@@ -18,13 +16,24 @@
use strict;
+package ObjectModel::Collection;
+
=head1 NAME
ObjectModel::Collection - Base class for item collections
-=cut
+=head1 DESCRIPTION
-package ObjectModel::Collection;
+Provides a set of methods to manipulate a collection of objects, and in
+particular load and save them to a database table using ObjectModel::BackEnd.
+Also provides a set of filtering methods to specify the set of objects we are
+interested in so only those objects are retrieved from the database.
+
+Note that there may be multiple collections corresponding to a given table at
+the same time. This is how one retrieves the objects based on different
+criteria.
+
+=cut
use vars qw(@ISA @EXPORT_OK);
diff --git a/testbot/lib/ObjectModel/DBIBackEnd.pm b/testbot/lib/ObjectModel/DBIBackEnd.pm
index f7098d5..5e61eed 100644
--- a/testbot/lib/ObjectModel/DBIBackEnd.pm
+++ b/testbot/lib/ObjectModel/DBIBackEnd.pm
@@ -21,6 +21,16 @@ use ObjectModel::BackEnd;
package ObjectModel::DBIBackEnd;
+=head1 NAME
+
+ObjectModel::DBIBackEnd - A storage backend implemented using DBI
+
+=head1 SEE ALSO
+
+ObjectModel::BackEnd
+
+=cut
+
use Time::Local;
use vars qw(@ISA @EXPORT);
diff --git a/testbot/lib/ObjectModel/DetailrefPropertyDescriptor.pm b/testbot/lib/ObjectModel/DetailrefPropertyDescriptor.pm
index d9cbfec..4832dd7 100644
--- a/testbot/lib/ObjectModel/DetailrefPropertyDescriptor.pm
+++ b/testbot/lib/ObjectModel/DetailrefPropertyDescriptor.pm
@@ -1,5 +1,3 @@
-# Item property description
-#
# Copyright 2009 Ge van Geldorp
#
# This library is free software; you can redistribute it and/or
@@ -18,14 +16,14 @@
use strict;
+package ObjectModel::DetailrefPropertyDescriptor;
+
=head1 NAME
-ObjectModel::PropertyDescriptor - Base class for item property descriptions
+ObjectModel::DetailrefPropertyDescriptor - A reference to a collection of related objects
=cut
-package ObjectModel::DetailrefPropertyDescriptor;
-
use vars qw(@ISA @EXPORT);
require Exporter;
diff --git a/testbot/lib/ObjectModel/EnumPropertyDescriptor.pm b/testbot/lib/ObjectModel/EnumPropertyDescriptor.pm
index b627189..3373c47 100644
--- a/testbot/lib/ObjectModel/EnumPropertyDescriptor.pm
+++ b/testbot/lib/ObjectModel/EnumPropertyDescriptor.pm
@@ -16,14 +16,18 @@
use strict;
+package ObjectModel::EnumPropertyDescriptor;
+
=head1 NAME
-ObjectModel::EnumPropertyDescriptor - Defines a property that can only take
-a set of values.
+ObjectModel::EnumPropertyDescriptor - Defines an enumeration property
-=cut
+=head1 DESCRIPTION
-package ObjectModel::EnumPropertyDescriptor;
+This handles the ENUM columns. In particular ValidateValue() checks that the
+new value is allowed.
+
+=cut
use ObjectModel::PropertyDescriptor;
diff --git a/testbot/lib/ObjectModel/Item.pm b/testbot/lib/ObjectModel/Item.pm
index 19b0c94..94ad8e6 100644
--- a/testbot/lib/ObjectModel/Item.pm
+++ b/testbot/lib/ObjectModel/Item.pm
@@ -1,5 +1,3 @@
-# Item
-#
# Copyright 2009 Ge van Geldorp
# Copyright 2012 Francois Gouget
#
@@ -19,14 +17,14 @@
use strict;
+package ObjectModel::Item;
+
=head1 NAME
ObjectModel::Item - Base class for items
=cut
-package ObjectModel::Item;
-
use ObjectModel::BackEnd;
use ObjectModel::Collection;
use ObjectModel::PropertyDescriptor;
diff --git a/testbot/lib/ObjectModel/ItemrefPropertyDescriptor.pm b/testbot/lib/ObjectModel/ItemrefPropertyDescriptor.pm
index 241d964..bf2a548 100644
--- a/testbot/lib/ObjectModel/ItemrefPropertyDescriptor.pm
+++ b/testbot/lib/ObjectModel/ItemrefPropertyDescriptor.pm
@@ -1,5 +1,3 @@
-# Item property description
-#
# Copyright 2009 Ge van Geldorp
#
# This library is free software; you can redistribute it and/or
@@ -18,14 +16,14 @@
use strict;
+package ObjectModel::ItemrefPropertyDescriptor;
+
=head1 NAME
-ObjectModel::PropertyDescriptor - Base class for item property descriptions
+ObjectModel::ItemrefPropertyDescriptor - A property referencing an ObjectModel::Item stored in another table
=cut
-package ObjectModel::ItemrefPropertyDescriptor;
-
use vars qw(@ISA @EXPORT);
require Exporter;
diff --git a/testbot/lib/ObjectModel/PropertyDescriptor.pm b/testbot/lib/ObjectModel/PropertyDescriptor.pm
index 87eff9e..5b5cbc4 100644
--- a/testbot/lib/ObjectModel/PropertyDescriptor.pm
+++ b/testbot/lib/ObjectModel/PropertyDescriptor.pm
@@ -1,6 +1,5 @@
-# Item property description
-#
# Copyright 2009 Ge van Geldorp
+# Copyright 2012 Francois Gouget
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
@@ -18,13 +17,19 @@
use strict;
+package ObjectModel::PropertyDescriptor;
+
=head1 NAME
ObjectModel::PropertyDescriptor - Base class for item property descriptions
-=cut
+=head1 DESCRIPTION
-package ObjectModel::PropertyDescriptor;
+This includes the basic information for retrieving and storing the property
+in the database, whether it is part of the primary key and whether it is
+required or not.
+
+=cut
use vars qw(@ISA @EXPORT);
diff --git a/testbot/lib/WineTestBot/Branches.pm b/testbot/lib/WineTestBot/Branches.pm
index 50182d4..ec80543 100644
--- a/testbot/lib/WineTestBot/Branches.pm
+++ b/testbot/lib/WineTestBot/Branches.pm
@@ -1,6 +1,5 @@
-# Branch collection and items
-#
# Copyright 2009 Ge van Geldorp
+# Copyright 2012 Francois Gouget
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
@@ -18,14 +17,14 @@
use strict;
+package WineTestBot::Branch;
+
=head1 NAME
-WineTestBot::Branches - Branch collection
+WineTestBot::Branch - Describes a Wine branch
=cut
-package WineTestBot::Branch;
-
use WineTestBot::WineTestBotObjects;
use WineTestBot::Config;
@@ -43,6 +42,12 @@ sub InitializeNew
package WineTestBot::Branches;
+=head1 NAME
+
+WineTestBot::Branches - A collection of WineTestBot::Branch objects
+
+=cut
+
use ObjectModel::BasicPropertyDescriptor;
use ObjectModel::PropertyDescriptor;
use WineTestBot::WineTestBotObjects;
diff --git a/testbot/lib/WineTestBot/Config.pm b/testbot/lib/WineTestBot/Config.pm
index aa9c7c7..a29f99c 100644
--- a/testbot/lib/WineTestBot/Config.pm
+++ b/testbot/lib/WineTestBot/Config.pm
@@ -1,5 +1,3 @@
-# WineTestBot configuration
-#
# Copyright 2009 Ge van Geldorp
#
# This library is free software; you can redistribute it and/or
@@ -18,14 +16,14 @@
use strict;
+package WineTestBot::Config;
+
=head1 NAME
-WineTestBot::Config - Configuration settings
+WineTestBot::Config - Site-independent configuration settings
=cut
-package WineTestBot::Config;
-
use ObjectModel::DBIBackEnd;
use vars qw (@ISA @EXPORT @EXPORT_OK $UseSSL $LogDir $DataDir $BinDir
diff --git a/testbot/lib/WineTestBot/Jobs.pm b/testbot/lib/WineTestBot/Jobs.pm
index 28d60ea..52de881 100644
--- a/testbot/lib/WineTestBot/Jobs.pm
+++ b/testbot/lib/WineTestBot/Jobs.pm
@@ -1,5 +1,3 @@
-# Job collection and items
-#
# Copyright 2009 Ge van Geldorp
# Copyright 2012 Francois Gouget
#
@@ -19,14 +17,38 @@
use strict;
+
+package WineTestBot::Job;
+
=head1 NAME
-WineTestBot::Jobs - Job collection
+WineTestBot::Job - A job submitted by a user
-=cut
+=head1 DESCRIPTION
+A Job is created when a WineTestBot::User asks for something to be tested
+(for automatically generated Jobs this would be the batch user). There are many
+paths that can result in the creation of a job:
-package WineTestBot::Job;
+=over
+
+=item *
+A use submits a patch or binary to test.
+
+=item *
+WineTestBot finds a patch to test on the mailing list (and has all the pieces
+it needs for that patch, see WineTestBot::PendingPatchSet).
+
+=item *
+WineTestBot notices a Wine commit round and decides to run the full suite of
+tests. In this case there is no WineTestBot::Patch object associated with the
+Job.
+
+=back
+
+A Job is composed of multiple WineTestBot::Step objects.
+
+=cut
use WineTestBot::Branches;
use WineTestBot::Engine::Notify;
@@ -270,6 +292,17 @@ sub GetDescription
package WineTestBot::Jobs;
+=head1 NAME
+
+WineTestBot::Jobs - A Job collection
+
+=head1 DESCRIPTION
+
+This collection contains all known jobs: those have have been run as well as
+those that are yet to be run.
+
+=cut
+
use POSIX qw(:errno_h);
use ObjectModel::BasicPropertyDescriptor;
use ObjectModel::EnumPropertyDescriptor;
@@ -415,6 +448,7 @@ sub ScheduleOnHost
return undef;
}
+ # Sort the VMs by decreasing order of priority of their Jobs
my @DirtyVMsByIndex = sort { $DirtyVMsBlockingJobs{$a} <=> $DirtyVMsBlockingJobs{$b} } keys %DirtyVMsBlockingJobs;
my $VMKey;
foreach $VMKey (@DirtyVMsByIndex)
@@ -454,6 +488,17 @@ sub ScheduleOnHost
return undef;
}
+=pod
+=over 12
+
+=item C<Schedule()>
+
+Goes through the WineTestBot hosts and schedules the Job tasks on each of
+them using WineTestBot::Jobs::ScheduleOnHost().
+
+=back
+=cut
+
sub Schedule
{
my $self = shift;
@@ -477,6 +522,21 @@ sub Schedule
return $ErrMessage;
}
+=pod
+=over 12
+
+=item C<Check()>
+
+Goes through the list of Jobs, and for each of them updates their status by
+checking whether they still have running Steps / Tasks, and whether those
+have succeeded or failed.
+
+As a side effect this also updates the status of the WineTestBot::Step and
+WineTestBot::Task objects.
+
+=back
+=cut
+
sub Check
{
my $self = shift;
diff --git a/testbot/lib/WineTestBot/Log.pm b/testbot/lib/WineTestBot/Log.pm
index 2b259da..a6762cc 100644
--- a/testbot/lib/WineTestBot/Log.pm
+++ b/testbot/lib/WineTestBot/Log.pm
@@ -1,5 +1,3 @@
-# WineTestBot logging
-#
# Copyright 2009 Ge van Geldorp
#
# This library is free software; you can redistribute it and/or
@@ -18,14 +16,14 @@
use strict;
+package WineTestBot::Log;
+
=head1 NAME
WineTestBot::Log - Logging
=cut
-package WineTestBot::Log;
-
use WineTestBot::Config;
use vars qw (@ISA @EXPORT);
diff --git a/testbot/lib/WineTestBot/Patches.pm b/testbot/lib/WineTestBot/Patches.pm
index bce6161..48c5f53 100644
--- a/testbot/lib/WineTestBot/Patches.pm
+++ b/testbot/lib/WineTestBot/Patches.pm
@@ -1,5 +1,3 @@
-# Patch collection and items
-#
# Copyright 2010 Ge van Geldorp
# Copyright 2012 Francois Gouget
#
@@ -19,14 +17,20 @@
use strict;
+package WineTestBot::Patch;
+
=head1 NAME
-WineTestBot::Patches - Patch collection
+WineTestBot::Patch - A patch to be tested
-=cut
+=head1 DESCRIPTION
+A WineTestBot::Patch object tracks a patch submitted by a user or collected
+from the mailing list. If it is part of a patch series, then a
+WineTestBot::PendingPatchSet object will be created to track the series and
+linked to this patch through a WineTestBot::PendingPatch object.
-package WineTestBot::Patch;
+=cut
use Encode qw/decode/;
use WineTestBot::Config;
@@ -52,6 +56,16 @@ sub InitializeNew
$self->SUPER::InitializeNew();
}
+=pod
+=over 12
+
+=item C<FromSubmission()>
+
+Initializes a WineTestBot::Patch object from the given message.
+
+=back
+=cut
+
sub FromSubmission
{
my $self = shift;
@@ -87,6 +101,24 @@ sub FromSubmission
$self->Disposition("Processing");
}
+=pod
+=over 12
+
+=item C<Submit()>
+
+Analyzes the current patch to determine which Wine tests are impacted. Then for
+each impacted test it creates a high priority WineTestBot::Job to run that test.
+This also creates the WineTestBot::Step objects for that Job, as well as the
+WineTestBot::Task objects to run the test on each 'base' VM. Finally it calls
+C<WineTestBot::Jobs::Schedule()> to run the new Jobs.
+
+Note that the path to the file containing the actual patch is passed as a
+parameter. This is used to apply a combined patch for patch series. See
+WineTestBot::PendingPatchSet::SubmitSubset().
+
+=back
+=cut
+
sub Submit
{
my $self = shift;
@@ -287,6 +319,12 @@ sub GetEMailRecipient
package WineTestBot::Patches;
+=head1 NAME
+
+WineTestBot::Patches - A collection of WineTestBot::Patch objects
+
+=cut
+
use ObjectModel::BasicPropertyDescriptor;
use ObjectModel::PropertyDescriptor;
use WineTestBot::Config;
@@ -364,6 +402,21 @@ sub IsTestPatch
return !1;
}
+=pod
+=over 12
+
+=item C<NewPatch()>
+
+Creates a WineTestBot::Patch object for the given message. If that the message
+does impact Wine's tests then the Patch object disposition is set and no
+further action is performed. Otherwise if the patch is part of a series then
+it gets tied to a WineTestBot::PendingPatchSet object by
+WineTestBot::PendingPatchSets::NewSubmission(). If the patch is independent of
+others, then C<WineTestBot::Patch::Submit()> is called right away.
+
+=back
+=cut
+
sub NewPatch
{
my $self = shift;
diff --git a/testbot/lib/WineTestBot/PendingPatchSets.pm b/testbot/lib/WineTestBot/PendingPatchSets.pm
index 84db07b..998c9d3 100644
--- a/testbot/lib/WineTestBot/PendingPatchSets.pm
+++ b/testbot/lib/WineTestBot/PendingPatchSets.pm
@@ -1,6 +1,5 @@
-# Incomplete patch series collection and items
-#
# Copyright 2009 Ge van Geldorp
+# Copyright 2012 Francois Gouget
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
@@ -18,14 +17,25 @@
use strict;
+package WineTestBot::PendingPatchSet;
+
=head1 NAME
-WineTestBot::PendingPatchSets - PendingPatchSet collection
+WineTestBot::PendingPatchSet - An object tracking a pending patchset
-=cut
+=head1 DESCRIPTION
+A patchset is a set of patches that depend on each other. They are numbered so
+that one knows in which order to apply them. This is typically indicated by a
+subject of the form '[3/5] Subject'. This means one must track which patchset
+a patch belongs to so it is tested (and applied) together with the earlier
+parts rather than in isolation. Furthermore the parts of the set may arrive in
+the wrong order so processing of later parts must be deferred until the earlier
+ones have been received.
-package WineTestBot::PendingPatchSet;
+The WineTestBot::PendingPatchSet class is where this tracking is implemented.
+
+=cut
use WineTestBot::Config;
use WineTestBot::Patches;
@@ -37,6 +47,17 @@ use vars qw(@ISA @EXPORT);
require Exporter;
@ISA = qw(WineTestBot::WineTestBotItem Exporter);
+=pod
+=over 12
+
+=item C<CheckSubsetComplete()>
+
+Returns true if all the patches needed for the specified part in the patchset
+have been received.
+
+=back
+=cut
+
sub CheckSubsetComplete
{
my $self = shift;
@@ -53,6 +74,16 @@ sub CheckSubsetComplete
return ! $MissingPart;
}
+=pod
+=over 12
+
+=item C<CheckComplete()>
+
+Returns true if all the patches of the patchset have been received.
+
+=back
+=cut
+
sub CheckComplete
{
my $self = shift;
@@ -60,6 +91,17 @@ sub CheckComplete
return $self->CheckSubsetComplete($self->TotalParts)
}
+=pod
+=over 12
+
+=item C<SubmitSubset()>
+
+Combines the patches leading to the specified part in the patchset, and then
+calls WineTestBot::Patch::Submit() so it gets scheduled for testing.
+
+=back
+=cut
+
sub SubmitSubset
{
my $self = shift;
@@ -100,6 +142,16 @@ sub SubmitSubset
return $ErrMessage;
}
+=pod
+=over 12
+
+=item C<Submit()>
+
+Submits the last patch in the patchset.
+
+=back
+=cut
+
sub Submit
{
my $self = shift;
@@ -110,6 +162,12 @@ sub Submit
package WineTestBot::PendingPatchSets;
+=head1 NAME
+
+WineTestBot::PendingPatchSets - A collection of WineTestBot::PendingPatchSet objects
+
+=cut
+
use ObjectModel::BasicPropertyDescriptor;
use ObjectModel::DetailrefPropertyDescriptor;
use WineTestBot::Config;
@@ -142,6 +200,18 @@ sub CreateItem
return WineTestBot::PendingPatchSet->new($self);
}
+=pod
+=over 12
+
+=item C<NewSubmission()>
+
+Adds a new part to the current patchset and submits it as well as all the
+other parts for which all the previous parts are available. If the new part
+makes the patchset complete, then the patchset itself is deleted.
+
+=back
+=cut
+
sub NewSubmission
{
my $self = shift;
@@ -230,6 +300,23 @@ sub NewSubmission
return $ErrMessage;
}
+=pod
+=over 12
+
+=item C<CheckForCompleteSet()>
+
+Goes over the pending patchsets and submits the patches for all those that
+are complete. See WineTestBot::PendingPatchSet::Submit().
+The WineTestBot::PendingPatchSet objects of all complete patchsets are also
+deleted.
+
+Note that this only submits the last patch in the set, because each part of a
+patchset is submitted as it becomes available so the earlier parts are supposed
+to have been submitted already.
+
+=back
+=cut
+
sub CheckForCompleteSet
{
my $self = shift;
diff --git a/testbot/lib/WineTestBot/PendingPatches.pm b/testbot/lib/WineTestBot/PendingPatches.pm
index 0fbe0a4..20934c7 100644
--- a/testbot/lib/WineTestBot/PendingPatches.pm
+++ b/testbot/lib/WineTestBot/PendingPatches.pm
@@ -1,6 +1,5 @@
-# Incomplete series part collection and items
-#
# Copyright 2009 Ge van Geldorp
+# Copyright 2012 Francois Gouget
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
@@ -18,13 +17,18 @@
use strict;
+package WineTestBot::PendingPatch;
+
=head1 NAME
-WineTestBot::PendingPatches - Incomplete series part collection
+WineTestBot::PendingPatch - Tracks the patches of an incomplete series
-=cut
+=head1 DESCRIPTION
-package WineTestBot::PendingPatch;
+Ties a WineTestBot::Patch object to the WineTestBot::PendingPatchSet object
+identifying the patch series it belongs to.
+
+=cut
use WineTestBot::WineTestBotObjects;
@@ -35,6 +39,12 @@ require Exporter;
package WineTestBot::PendingPatches;
+=head1 NAME
+
+WineTestBot::PendingPatches - A collection of WineTestBot::PendingPatch objects
+
+=cut
+
use ObjectModel::BasicPropertyDescriptor;
use ObjectModel::ItemrefPropertyDescriptor;
use ObjectModel::PropertyDescriptor;
diff --git a/testbot/lib/WineTestBot/Roles.pm b/testbot/lib/WineTestBot/Roles.pm
index 8327ff9..620566a 100644
--- a/testbot/lib/WineTestBot/Roles.pm
+++ b/testbot/lib/WineTestBot/Roles.pm
@@ -1,5 +1,3 @@
-# Role collection and items
-#
# Copyright 2009 Ge van Geldorp
#
# This library is free software; you can redistribute it and/or
@@ -18,13 +16,17 @@
use strict;
+package WineTestBot::Role;
+
=head1 NAME
-WineTestBot::Roles - Role collection
+WineTestBot::Role - A Role item
-=cut
+=head1 DESCRIPTION
-package WineTestBot::Role;
+A Role is a class of users and defines what they can do.
+
+=cut
use WineTestBot::WineTestBotObjects;
@@ -41,6 +43,12 @@ sub HasRole
package WineTestBot::Roles;
+=head1 NAME
+
+WineTestBot::Roles - A collection of WineTestBot::Role objects
+
+=cut
+
use ObjectModel::PropertyDescriptor;
use ObjectModel::BasicPropertyDescriptor;
use WineTestBot::WineTestBotObjects;
diff --git a/testbot/lib/WineTestBot/Steps.pm b/testbot/lib/WineTestBot/Steps.pm
index c1fd972..ccfac79 100644
--- a/testbot/lib/WineTestBot/Steps.pm
+++ b/testbot/lib/WineTestBot/Steps.pm
@@ -1,5 +1,3 @@
-# Job step collection and items
-#
# Copyright 2009 Ge van Geldorp
# Copyright 2012 Francois Gouget
#
@@ -19,13 +17,19 @@
use strict;
+package WineTestBot::Step;
+
=head1 NAME
-WineTestBot::Steps - Job step collection
+WineTestBot::Step - A Job's Step
-=cut
+=head1 DESCRIPTION
-package WineTestBot::Step;
+A Job is composed of multiple Steps that each do a specific operation: build
+the test executable, or run a given test, etc. A Step is in turn composed of
+a WineTestBot::Task object for each VM it should be run on.
+
+=cut
use File::Copy;
use WineTestBot::Config;
@@ -88,6 +92,12 @@ sub HandleStaging
package WineTestBot::Steps;
+=head1 NAME
+
+WineTestBot::Steps - A collection of Job Steps
+
+=cut
+
use ObjectModel::BasicPropertyDescriptor;
use ObjectModel::EnumPropertyDescriptor;
use ObjectModel::DetailrefPropertyDescriptor;
diff --git a/testbot/lib/WineTestBot/StepsTasks.pm b/testbot/lib/WineTestBot/StepsTasks.pm
index 8ca7510..4ffd812 100644
--- a/testbot/lib/WineTestBot/StepsTasks.pm
+++ b/testbot/lib/WineTestBot/StepsTasks.pm
@@ -1,6 +1,5 @@
-# Merged job steps/tasks
-#
# Copyright 2009 Ge van Geldorp
+# Copyright 2012 Francois Gouget
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
@@ -18,13 +17,18 @@
use strict;
+package WineTestBot::StepTask;
+
=head1 NAME
-WineTestBot::StepsTasks - Job step/tasks collection
+WineTestBot::StepTask - Merged job steps/tasks
-=cut
+=head1 DESCRIPTION
-package WineTestBot::StepTask;
+This ties together a given WineTestBot::Task object with the corresponding
+WineTestBot::Step object.
+
+=cut
use WineTestBot::Config;
use WineTestBot::WineTestBotObjects;
@@ -71,6 +75,12 @@ sub GetTitle
package WineTestBot::StepsTasks;
+=head1 NAME
+
+WineTestBot::StepsTasks - A collection of StepsTasks objects
+
+=cut
+
use ObjectModel::BasicPropertyDescriptor;
use ObjectModel::ItemrefPropertyDescriptor;
use ObjectModel::PropertyDescriptor;
diff --git a/testbot/lib/WineTestBot/Tasks.pm b/testbot/lib/WineTestBot/Tasks.pm
index cd42ae5..2630ee2 100644
--- a/testbot/lib/WineTestBot/Tasks.pm
+++ b/testbot/lib/WineTestBot/Tasks.pm
@@ -1,5 +1,3 @@
-# Individual task of a job collection and items
-#
# Copyright 2009 Ge van Geldorp
# Copyright 2012 Francois Gouget
#
@@ -19,13 +17,20 @@
use strict;
+package WineTestBot::Task;
+
=head1 NAME
-WineTestBot::Tasks - Job task collection
+WineTestBot::Task - A task associated with a given WineTestBot::Step object
-=cut
+=head1 DESCRIPTION
-package WineTestBot::Task;
+A WineTestBot::Step is composed of one or more Tasks, each responsible for
+performing that Step in a WineTestBot::VM virtual machine. For instance a Step
+responsible for running a given test would have one Task object for each
+virtual machine that the test must be performed in.
+
+=cut
use ObjectModel::BackEnd;
use WineTestBot::Config;
@@ -50,6 +55,21 @@ sub InitializeNew
$self->SUPER::InitializeNew(@_);
}
+=pod
+=over 12
+
+=item C<Run()>
+
+Starts a script in the background to execute the specified task. The command is
+of the form:
+
+ ${ProjectName}Run${Type}.pl ${JobId} ${StepNo} ${TaskNo}
+
+Where $Type corresponds to the Task's type.
+
+=back
+=cut
+
sub Run
{
my $self = shift;
@@ -100,6 +120,12 @@ sub Run
package WineTestBot::Tasks;
+=head1 NAME
+
+WineTestBot::Tasks - A collection of WineTestBot::Task objects
+
+=cut
+
use ObjectModel::BasicPropertyDescriptor;
use ObjectModel::EnumPropertyDescriptor;
use ObjectModel::ItemrefPropertyDescriptor;
diff --git a/testbot/lib/WineTestBot/UserRoles.pm b/testbot/lib/WineTestBot/UserRoles.pm
index 3772b0a..04d6059 100644
--- a/testbot/lib/WineTestBot/UserRoles.pm
+++ b/testbot/lib/WineTestBot/UserRoles.pm
@@ -1,5 +1,3 @@
-# Role of a user collection and items
-#
# Copyright 2009 Ge van Geldorp
#
# This library is free software; you can redistribute it and/or
@@ -18,14 +16,14 @@
use strict;
+package WineTestBot::UserRole;
+
=head1 NAME
-WineTestBot::UserRoles - User role collection
+WineTestBot::UserRole - A UserRole item
=cut
-package WineTestBot::UserRole;
-
use WineTestBot::WineTestBotObjects;
use vars qw(@ISA @EXPORT);
@@ -35,6 +33,12 @@ require Exporter;
package WineTestBot::UserRoles;
+=head1 NAME
+
+WineTestBot::UserRoles - A collection of WineTestBot::UserRole objects
+
+=cut
+
use ObjectModel::ItemrefPropertyDescriptor;
use ObjectModel::PropertyDescriptor;
use WineTestBot::Roles;
diff --git a/testbot/lib/WineTestBot/Users.pm b/testbot/lib/WineTestBot/Users.pm
index f50029f..d5ed7d3 100644
--- a/testbot/lib/WineTestBot/Users.pm
+++ b/testbot/lib/WineTestBot/Users.pm
@@ -1,5 +1,3 @@
-# User collection and items
-#
# Copyright 2009 Ge van Geldorp
#
# This library is free software; you can redistribute it and/or
@@ -18,14 +16,14 @@
use strict;
+package WineTestBot::User;
+
=head1 NAME
-WineTestBot::Users - User collection
+WineTestBot::Users - A User
=cut
-package WineTestBot::User;
-
use Digest::SHA qw(sha1_hex);
use URI::Escape;
use WineTestBot::Config;
@@ -299,6 +297,12 @@ sub HasRole
package WineTestBot::Users;
+=head1 NAME
+
+WineTestBot::Users - A collection of WineTestBot::User objects
+
+=cut
+
use Net::LDAP;
use ObjectModel::BasicPropertyDescriptor;
use ObjectModel::DetailrefPropertyDescriptor;
diff --git a/testbot/lib/WineTestBot/Utils.pm b/testbot/lib/WineTestBot/Utils.pm
index e7996ca..acfabb5 100644
--- a/testbot/lib/WineTestBot/Utils.pm
+++ b/testbot/lib/WineTestBot/Utils.pm
@@ -1,5 +1,3 @@
-# WineTestBot utilities
-#
# Copyright 2009 Ge van Geldorp
#
# This library is free software; you can redistribute it and/or
@@ -18,14 +16,14 @@
use strict;
+package WineTestBot::Utils;
+
=head1 NAME
WineTestBot::Utils - Utility functions
=cut
-package WineTestBot::Utils;
-
use WineTestBot::Config;
use vars qw (@ISA @EXPORT);
diff --git a/testbot/lib/WineTestBot/WineTestBotObjects.pm b/testbot/lib/WineTestBot/WineTestBotObjects.pm
index 3eef25d..5671d9a 100644
--- a/testbot/lib/WineTestBot/WineTestBotObjects.pm
+++ b/testbot/lib/WineTestBot/WineTestBotObjects.pm
@@ -1,5 +1,3 @@
-# Base collection and item classes for WineTestBot
-#
# Copyright 2009-2011 Ge van Geldorp
#
# This library is free software; you can redistribute it and/or
@@ -18,14 +16,14 @@
use strict;
+package WineTestBot::WineTestBotItem;
+
=head1 NAME
-WineTestBot::WineTestBotCollection - Base collection class for WineTestBot
+WineTestBot::WineTestBotItem - Base item class for WineTestBot
=cut
-package WineTestBot::WineTestBotItem;
-
use ObjectModel::BackEnd;
use ObjectModel::Item;
use WineTestBot::Config;
@@ -40,8 +38,15 @@ sub GetBackEnd
return $ActiveBackEnds{'WineTestBot'};
}
+
package WineTestBot::WineTestBotCollection;
+=head1 NAME
+
+WineTestBot::WineTestBotCollection - Base collection class for WineTestBot
+
+=cut
+
use ObjectModel::BackEnd;
use ObjectModel::Item;
use WineTestBot::Config;
--
1.7.10.4
More information about the wine-patches
mailing list