[libgda] GdaData.Object added doc and API change now is Generic with new append() function

[Daniel Espinosa Ortiz <despinosa src gnome org>]

commit 58500c73533c4bd9f24fe2d694153c5ad43b7e67
Author: Daniel Espinosa <despinosa src gnome org>
Date:   Mon Jan 2 16:21:03 2012 -0600

    GdaData.Object added doc and API change now is Generic with new append() function
    
    * Object is now generic you need to define the returning type of append().
    * New append() must be implemented by derived classes throwing ObjectError
    domains set to APPEND. Expected generic type mustbe the derived class.
    * Added documentation to functions. No gtk-doc or valadoc for now.

 libgda/data/DataObject.vala |   39 +++++++++++++++++++++++++++++++++++++--
 libgda/data/GdaData-5.0.gir |   27 +++++++++++++++++++++++++++
 2 files changed, 64 insertions(+), 2 deletions(-)
---
diff --git a/libgda/data/DataObject.vala b/libgda/data/DataObject.vala
index f926e98..3a62efd 100644
--- a/libgda/data/DataObject.vala
+++ b/libgda/data/DataObject.vala
@@ -19,23 +19,34 @@
 
 using Gda;
 
-[CCode (gir_namespace = "GdaData", gir_version = "5.0", cheader_filename="libgda/libgdadata.h")]
 namespace GdaData {
 
-    public abstract class Object : GLib.Object {
+    public errordomain ObjectError {
+    	APPEND
+    }
+    public abstract class Object<G> : GLib.Object {
         
         private string? _field_id;
         private Value? _id_value;
         private DataModel _model;
         
+        /**
+         * Derived classes must implement this property to set the table used to get data from.
+         */
         public abstract string table { get; }
         
+        /**
+         * Returns a Gda.DataModel with the data stored by this object.
+         */
         public DataModel record {
         	get {
         		return this._model;
         	}
         }
         
+        /**
+         * Set the connection to be used to get/set data.
+         */
         public Connection connection { get; set; }
         
         public string get_field_id ()
@@ -64,24 +75,37 @@ namespace GdaData {
         	this._model= (DataModel) DataProxy.new (m);
         }
         
+        /**
+         * Returns a GLib.Value containing the value stored in the given field.
+         */
         public unowned Value? get_value (string field)
         	throws Error
         {
         	return this._model.get_value_at (this._model.get_column_index (field), 0);
         }
         
+        /**
+         * Set the value to a field with the given @name
+         */
         public void set_value (string field, Value v)
         	throws Error
         {
         	this._model.set_value_at (this._model.get_column_index (field), 0, v);
         }
         
+        /**
+         * Saves any modficiation made to in memory representation of the data directly to
+         * the database.
+         */
         public void save ()
         	throws Error
         {
         	((DataProxy) this._model).apply_all_changes ();
         }
         
+        /**
+         * Re-load the data stored in the dabase.
+         */
         public void update ()
         	throws Error
         	requires (this.table != "")
@@ -89,6 +113,10 @@ namespace GdaData {
         	set_id (this._field_id, this._id_value);
         }
         
+        /**
+         * Returns a #SqlBuilder object with the query used to select the data in the used
+         * that points this object to.
+         */
         public SqlBuilder sql ()
         	requires (this.table != null || this.table != "")
         	requires (this._field_id != null || this._field_id != "")
@@ -103,5 +131,12 @@ namespace GdaData {
 			q.select_add_field ("*", null, null);
 			return q;			
         }
+        
+        /**
+         * abstract function to be implemented in derived classes to add new objects to the database.<BR>
+         * 
+         * Error code must be ObjectError.APPEND.
+         */
+        public abstract G append () throws ObjectError;
     }
 }
diff --git a/libgda/data/GdaData-5.0.gir b/libgda/data/GdaData-5.0.gir
index 947ced4..7a04cb4 100644
--- a/libgda/data/GdaData-5.0.gir
+++ b/libgda/data/GdaData-5.0.gir
@@ -9,6 +9,11 @@
 	<annotation key="ccode.gir-version" value="5.0"/>
 	<annotation key="ccode.cheader-filename" value="libgda/libgdadata.h"/>
 	<annotation key="ccode.gir-namespace" value="GdaData"/>
+	<errordomain name="ObjectError" get-quark="gda_data_object_error_quark" codes="ObjectError">
+</errordomain>
+	<enumeration name="ObjectError" c:type="GdaDataObjectError">
+		<member name="append" c:identifier="GDA_DATA_OBJECT_ERROR_APPEND" value="0"/>
+	</enumeration>
 	<class name="Object" c:type="GdaDataObject" glib:type-name="GdaDataObject" glib:get-type="gda_data_object_get_type" glib:type-struct="ObjectClass" parent="GObject.Object" abstract="1">
 		<field name="parent_instance">
 			<type name="GObject.Object" c:type="GObject"/>
@@ -82,6 +87,16 @@
 				<type name="Gda.SqlBuilder" c:type="GdaSqlBuilder*"/>
 			</return-value>
 		</method>
+		<method name="append" c:identifier="gda_data_object_append" throws="1">
+			<return-value transfer-ownership="full" allow-none="1">
+				<type name="gpointer" c:type="gpointer"/>
+			</return-value>
+		</method>
+		<virtual-method name="append" invoker="append" throws="1">
+			<return-value transfer-ownership="full" allow-none="1">
+				<type name="gpointer" c:type="gpointer"/>
+			</return-value>
+		</virtual-method>
 		<property name="table">
 			<type name="utf8" c:type="gchar*"/>
 		</property>
@@ -96,6 +111,18 @@
 		<field name="parent_class">
 			<type name="GObject.ObjectClass" c:type="GObjectClass"/>
 		</field>
+				<field name="append">
+			<callback name="append" c:type="append" throws="1">
+				<parameters>
+					<parameter name="self" transfer-ownership="none">
+						<type name="GdaData.Object" c:type="GdaDataObject*"/>
+					</parameter>
+				</parameters>
+				<return-value transfer-ownership="full" allow-none="1">
+					<type name="gpointer" c:type="gpointer"/>
+				</return-value>
+			</callback>
+		</field>
 	</record>
 	<record name="ObjectPrivate" c:type="GdaDataObjectPrivate" disguised="1"/>
 	<class name="DbField" c:type="GdaDataDbField" glib:type-name="GdaDataDbField" glib:get-type="gda_data_db_field_get_type" glib:type-struct="DbFieldClass" parent="GObject.Object" abstract="1">