[gnome-db] GdaDataModel virtual functions API question + new PATCH

[Daniel Espinosa <esodan gmail com>]

I'm continuing adding more and more annotations in libgda-4.2 (find attached another PATCH :-), I'm adding Virtual: annotations to GdaDataModel and found that the following virtual functions:

        [NoWrapper]
        public abstract bool i_iter_at_row (Gda.DataModelIter iter, int row);
        [NoWrapper]
        public abstract bool i_iter_next (Gda.DataModelIter iter);
        [NoWrapper]
        public abstract bool i_iter_prev (Gda.DataModelIter iter);
        [NoWrapper]
        public abstract bool i_iter_set_value (Gda.DataModelIter iter, int col, GLib.Value value) throws GLib.Error;

* Must not be part of GdaDataModel* because they are functions of GdaDataModelter. Remove this functions in libgda-5.0 could be good to cleaning the API.

The following virtual function have a static function and no public function to use it, is this correct? Must be removed from the virtual functions API in 5.0?

        [NoWrapper]
        public abstract bool i_get_notify ();

I'm finding more API comments from the generated VAPI file on Utility: most functions must be in the object used by them to perform the action.
diff --git a/libgda/Gda-4.0.metadata b/libgda/Gda-4.0.metadata
new file mode 100644
index 0000000..6502e38
--- /dev/null
+++ b/libgda/Gda-4.0.metadata
@@ -0,0 +1,30 @@
+// Vala Bindings for GDA
+Gda cheader_filename="libgda/libgda.h"
+ValueList type="GLib.List<GLib.Value>"
+ServerProviderMeta skip
+ServerProviderXa skip
+// libxml2: replace xml.NodePtr by xml.Node* used by Vala bindings
+Set.new_from_spec_node.xml_spec type="Xml.Node*"
+DataModel.add_data_from_xml_node.node type="Xml.Node*"
+utility_data_model_dump_data_to_xml.parent type="Xml.Node*"
+utility_holder_load_attributes.node type="Xml.Node*"
+value_new_from_xml.node type="Xml.Node*"
+DataModelImport.new_xml_node.node type="Xml.Node*"
+ServerOperation.load_data_from_xml.node type="Xml.Node*"
+// type overrides for GIR not well detected
+MetaStore.meta_changed.changes type="GLib.SList<Gda.MetaStoreChange>"
+MetaStore.meta_changed.changes out=true
+PStmt.param_ids type="GLib.List<string>"
+PStmt.tmpl_columns type="GLib.List<Gda.Column>"
+ServerProvider.statement_to_sql.params_used type="GLib.List<Gda.Holder>"
+Set.groups_list type="GLib.List<Gda.SetGroup>"
+Set.nodes_list type="GLib.List<Gda.SetNode>"
+Set.sources_list type="GLib.List<Gda.SetSource>"
+TransactionStatus.events type="GLib.List<Gda.TransactionStatusEvent>"
+MetaDbObject.depend_list type="GLib.List<Gda.MetaDbObject>"
+MetaTable.columns type="GLib.List<Gda.MetaTableColumn>"
+MetaTable.reverse_fk_list type="GLib.List<Gda.MetaTableForeignKey>"
+MetaTable.fk_list type="GLib.List<Gda.MetaTableForeignKey>"
+SetGroup.nodes type="GLib.List<Gda.SetNode>"
+SetSource.nodes type="GLib.List<Gda.SetNode>"
+SqlRenderingContext.params_used type="GLib.List<Gda.Holder>"
diff --git a/libgda/gda-connection.c b/libgda/gda-connection.c
index 8901717..cd27686 100644
--- a/libgda/gda-connection.c
+++ b/libgda/gda-connection.c
@@ -2742,7 +2742,7 @@ gda_connection_quote_sql_identifier (GdaConnection *cnc, const gchar *id)
  * @stmt: a #GdaStatement object
  * @params: (allow-none): a #GdaSet object (which can be obtained using gda_statement_get_parameters()), or %NULL
  * @flags: SQL rendering flags, as #GdaStatementSqlFlag OR'ed values
- * @params_used: (allow-none) (element-type GdaHolder) (out) (transfer container): a place to store the list of individual #GdaHolder objects within @params which have been used
+ * @params_used: (allow-none) (element-type Gda.Holder) (out) (transfer container): a place to store the list of individual #GdaHolder objects within @params which have been used
  * @error: a place to store errors, or %NULL
  *
  * Renders @stmt as an SQL statement, adapted to the SQL dialect used by @cnc
diff --git a/libgda/gda-data-model.c b/libgda/gda-data-model.c
index bea0cd6..d2e4281 100644
--- a/libgda/gda-data-model.c
+++ b/libgda/gda-data-model.c
@@ -361,6 +361,8 @@ gda_data_model_reset (GdaDataModel *model)
  * Disables notifications of changes on the given data model. To
  * re-enable notifications again, you should call the
  * #gda_data_model_thaw function.
+ *
+ * Virtual: i_set_notify
  */
 void
 gda_data_model_freeze (GdaDataModel *model)
@@ -397,6 +399,8 @@ gda_data_model_thaw (GdaDataModel *model)
  * Get the attributes of @model such as how to access the data it contains if it's modifiable, etc.
  *
  * Returns: (transfer none): an ORed value of #GdaDataModelAccessFlags flags
+ *
+ * Virtual: i_get_access_flags
  */
 GdaDataModelAccessFlags
 gda_data_model_get_access_flags (GdaDataModel *model)
@@ -417,6 +421,8 @@ gda_data_model_get_access_flags (GdaDataModel *model)
  * @model: a #GdaDataModel object.
  *
  * Returns: the number of rows in the given data model, or -1 if the number of rows is not known
+ *
+ * Virtual: i_get_n_rows
  */
 gint
 gda_data_model_get_n_rows (GdaDataModel *model)
@@ -434,6 +440,8 @@ gda_data_model_get_n_rows (GdaDataModel *model)
  * @model: a #GdaDataModel object.
  *
  * Returns: the number of columns in the given data model.
+ *
+ * Virtual: i_get_n_columns
  */
 gint
 gda_data_model_get_n_columns (GdaDataModel *model)
@@ -463,6 +471,8 @@ gda_data_model_get_n_columns (GdaDataModel *model)
  * and should not be destroyed; any modification will affect the whole data model.
  *
  * Returns: (transfer none): the description of the column.
+ *
+ * Virtual: i_describe_column
  */
 GdaColumn *
 gda_data_model_describe_column (GdaDataModel *model, gint col)
@@ -636,6 +646,8 @@ gda_data_model_set_column_title (GdaDataModel *model, gint col, const gchar *tit
  *
  * Returns: (transfer none): a #GValue containing the value stored in the given
  * position, or %NULL on error (out-of-bound position, etc).
+ *
+ * Virtual: i_get_value_at
  */
 const GValue *
 gda_data_model_get_value_at (GdaDataModel *model, gint col, gint row, GError **error)
@@ -720,6 +732,8 @@ gda_data_model_get_typed_value_at (GdaDataModel *model, gint col, gint row, GTyp
  * if a row was added to @model.
  *
  * Returns: (transfer none): the attributes as an ORed value of #GdaValueAttribute
+ *
+ * Virtual: i_get_attributes_at
  */
 GdaValueAttribute
 gda_data_model_get_attributes_at (GdaDataModel *model, gint col, gint row)
@@ -752,6 +766,8 @@ gda_data_model_get_attributes_at (GdaDataModel *model, gint col, gint row)
  * #GError from the #GDA_DATA_MODEL_ERROR domain.
  *
  * Returns: TRUE if the value in the data model has been updated and no error occurred
+ *
+ * Virtual: i_set_value_at
  */
 gboolean
 gda_data_model_set_value_at (GdaDataModel *model, gint col, gint row, const GValue *value, GError **error)
@@ -851,6 +867,8 @@ gda_data_model_set_values (GdaDataModel *model, gint row, GList *values, GError
  * <programlisting><![CDATA[iter = g_object_new (GDA_TYPE_DATA_MODEL_ITER, "data-model", proxy, NULL);]]></programlisting>
  *
  * Returns: (transfer full): a #GdaDataModelIter object, or %NULL if an error occurred
+ *
+ * Virtual: i_create_iter
  */
 GdaDataModelIter *
 gda_data_model_create_iter (GdaDataModel *model)
@@ -879,6 +897,8 @@ gda_data_model_create_iter (GdaDataModel *model)
  * #GError from the #GDA_DATA_MODEL_ERROR domain.
  *
  * Returns: the number of the added row, or -1 if an error occurred
+ *
+ * Virtual: i_append_values
  */
 gint
 gda_data_model_append_values (GdaDataModel *model, const GList *values, GError **error)
@@ -907,6 +927,8 @@ gda_data_model_append_values (GdaDataModel *model, const GList *values, GError *
  * #GError from the #GDA_DATA_MODEL_ERROR domain.
  *
  * Returns: the number of the added row, or -1 if an error occurred
+ *
+ * Virtual: i_append_row
  */
 gint
 gda_data_model_append_row (GdaDataModel *model, GError **error)
@@ -942,6 +964,8 @@ gda_data_model_append_row (GdaDataModel *model, GError **error)
  * #GError from the #GDA_DATA_MODEL_ERROR domain.
  *
  * Returns: %TRUE if successful, %FALSE otherwise.
+ *
+ * Virtual: i_remove_row
  */
 gboolean
 gda_data_model_remove_row (GdaDataModel *model, gint row, GError **error)
@@ -976,6 +1000,8 @@ gda_data_model_remove_row (GdaDataModel *model, gint row, GError **error)
  * NOTE: the @cols_index array MUST contain a column index for each value in @values
  *
  * Returns: the requested row number, of -1 if not found
+ *
+ * Virtual: i_find_row
  */
 gint
 gda_data_model_get_row_from_values (GdaDataModel *model, GSList *values, gint *cols_index)
@@ -1044,6 +1070,8 @@ gda_data_model_get_row_from_values (GdaDataModel *model, GSList *values, gint *c
  *
  * Sends a hint to the data model. The hint may or may not be handled by the data
  * model, depending on its implementation
+ *
+ * Virtual: i_send_hint
  */
 void
 gda_data_model_send_hint (GdaDataModel *model, GdaDataModelHint hint, const GValue *hint_value)
diff --git a/libgda/gda-server-provider.h b/libgda/gda-server-provider.h
index 69edf25..2d1dfe1 100644
--- a/libgda/gda-server-provider.h
+++ b/libgda/gda-server-provider.h
@@ -279,6 +279,20 @@ struct _GdaServerProviderClass {
 
 	/* GdaStatement */
 	GdaSqlParser           *(* create_parser)        (GdaServerProvider *provider, GdaConnection *cnc);
+
+	/**
+	 * statement_to_sql:
+	 * @cnc: a #GdaConnection object
+	 * @stmt: a #GdaStatement object
+	 * @params: (allow-none): a #GdaSet object (which can be obtained using gda_statement_get_parameters()), or %NULL
+	 * @flags: SQL rendering flags, as #GdaStatementSqlFlag OR'ed values
+	 * @params_used: (allow-none) (element-type Gda.Holder) (out) (transfer container): a place to store the list of individual #GdaHolder objects within @params which have been used
+	 * @error: a place to store errors, or %NULL
+	 *
+	 * Renders @stmt as an SQL statement, adapted to the SQL dialect used by @cnc
+	 *
+	 * Returns: a new string, or %NULL if an error occurred
+	 */
 	gchar                  *(* statement_to_sql)     (GdaServerProvider *provider, GdaConnection *cnc, 
 							  GdaStatement *stmt, GdaSet *params, GdaStatementSqlFlag flags,
 							  GSList **params_used, GError **error);