Francois Gouget : testbot/orm: Add documentation to the database backend.

[Alexandre Julliard]

Module: tools
Branch: master
Commit: 9aa433e3178d138cb9b4e0cbb74167292e5ca450
URL:    https://source.winehq.org/git/tools.git/?a=commit;h=9aa433e3178d138cb9b4e0cbb74167292e5ca450

Author: Francois Gouget <fgouget at codeweavers.com>
Date:   Mon May 30 18:44:22 2022 +0200

testbot/orm: Add documentation to the database backend.

Signed-off-by: Francois Gouget <fgouget at codeweavers.com>
Signed-off-by: Alexandre Julliard <julliard at winehq.org>

---

 testbot/lib/ObjectModel/DBIBackEnd.pm | 107 ++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)

diff --git a/testbot/lib/ObjectModel/DBIBackEnd.pm b/testbot/lib/ObjectModel/DBIBackEnd.pm
index dc527d4..94e4be6 100644
--- a/testbot/lib/ObjectModel/DBIBackEnd.pm
+++ b/testbot/lib/ObjectModel/DBIBackEnd.pm
@@ -63,6 +63,17 @@ sub GetDb($)
   return $self->{Db};
 }
 
+=pod
+=over 12
+
+=item C<ToDb()>
+
+Convert the property value to a format suitable for the database.
+This is only needed for boolean and timestamp properties.
+
+=back
+=cut
+
 sub ToDb($$$)
 {
   my ($self, $Value, $PropertyDescriptor) = @_;
@@ -101,6 +112,16 @@ sub ToDb($$$)
   return $Value;
 }
 
+=pod
+=over 12
+
+=item C<FromDb()>
+
+Convert the database values to a format suitable for Perl. See ToDb().
+
+=back
+=cut
+
 sub FromDb($$$)
 {
   my ($self, $Value, $PropertyDescriptor) = @_;
@@ -132,6 +153,18 @@ sub FromDb($$$)
   return $Value;
 }
 
+=pod
+=over 12
+
+=item C<BuildKeyWhere()>
+
+Augments the specified WHERE clause with statements to match the key columns.
+It is up to the caller to then append the corresponding key components to the
+query's data array.
+
+=back
+=cut
+
 sub BuildKeyWhere($$$)
 {
   my ($self, $PropertyDescriptors, $Where) = @_;
@@ -154,6 +187,17 @@ sub BuildKeyWhere($$$)
   return $Where;
 }
 
+=pod
+=over 12
+
+=item C<BuildFieldList()>
+
+Build the comma-separated SELECT list of columns to load from the database.
+Note that only the non-master columns are loaded.
+
+=back
+=cut
+
 sub BuildFieldList($$)
 {
   my ($self, $PropertyDescriptors) = @_;
@@ -277,6 +321,19 @@ sub GetFilterWhere($$$)
   die "unsupported '$Filter->{Type}' filter type";
 }
 
+=pod
+=over 12
+
+=item C<LoadCollection()>
+
+Loads the collection from the corresponding database table, filtering it on
+both the master columns and the collection's filter if any.
+
+Note that only the non-master columns are loaded (see BuildFieldList()).
+
+=back
+=cut
+
 sub LoadCollection($$)
 {
   my ($self, $Collection) = @_;
@@ -346,6 +403,8 @@ By design this method will not check if the Item is already present in the
 Collection scope. Such checks belong in the higher levels. This method will
 however put the Item in the Collection's scope.
 
+Note that only the non-master columns are loaded (see BuildFieldList()).
+
 =back
 =cut
 
@@ -395,6 +454,17 @@ sub LoadItem($$$)
   return $Item;
 }
 
+=pod
+=over 12
+
+=item C<BuildInsertStatement()>
+
+Builds the SQL statement for saving new Items to the database.
+This can be reused multiple times when saving a collection.
+
+=back
+=cut
+
 sub BuildInsertStatement($$$$)
 {
   my ($self, $TableName, $PropertyDescriptors, $MasterColNames) = @_;
@@ -432,6 +502,18 @@ sub BuildInsertStatement($$$$)
   return "INSERT INTO $TableName ($Fields) VALUES($PlaceHolders)";
 }
 
+=pod
+=over 12
+
+=item C<GetInsertData()>
+
+Builds a data array suitable for use with the SQL statement returned by
+BuildInsertStatement() for the specified Item. This simply includes all
+of the object's properties.
+
+=back
+=cut
+
 sub GetInsertData($$$)
 {
   my ($self, $MasterColValues, $Item) = @_;
@@ -454,6 +536,17 @@ sub GetInsertData($$$)
   return \@Data;
 }
 
+=pod
+=over 12
+
+=item C<BuildUpdateStatement()>
+
+Builds the SQL statement for saving *modified* Items to the database.
+This can be reused multiple times when saving a collection.
+
+=back
+=cut
+
 sub BuildUpdateStatement($$$$)
 {
   my ($self, $TableName, $PropertyDescriptors, $MasterColNames) = @_;
@@ -484,6 +577,20 @@ sub BuildUpdateStatement($$$$)
   return "UPDATE $TableName SET $Fields WHERE $Where";
 }
 
+=pod
+=over 12
+
+=item C<GetUpdateData()>
+
+Returns a data array suitable for use with the SQL statement returned by
+BuildUpdateStatement() for the specified Item. It is composed of:
+* The non-key properties for the SET part of the statement since only those
+  could have been modified.
+* The key properties for the WHERE part of the statement.
+
+=back
+=cut
+
 sub GetUpdateData($$$)
 {
   my ($self, $MasterColValues, $Item) = @_;