[libgda] More introspection annotations for Libgda
- From: Vivien Malerba <vivien src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [libgda] More introspection annotations for Libgda
- Date: Tue, 21 Sep 2010 18:55:35 +0000 (UTC)
commit eebb8fda0be8b7cdf2b3d8dd093d5e5605d22545
Author: Vivien Malerba <malerba gnome-db org>
Date: Tue Sep 21 20:53:23 2010 +0200
More introspection annotations for Libgda
libgda/gda-data-proxy.c | 7 +-
libgda/gda-meta-store.c | 101 +++++++++---------
libgda/gda-meta-struct-io.c | 14 ++-
libgda/gda-meta-struct.c | 79 +++++++-------
libgda/gda-mutex.c | 14 ++--
libgda/gda-quark-list.c | 18 ++--
libgda/gda-repetitive-statement.c | 22 +++--
libgda/gda-row.c | 16 ++--
libgda/gda-server-operation.c | 76 +++++++-------
libgda/gda-server-provider-extra.c | 51 +++++----
libgda/gda-server-provider.c | 103 +++++++++---------
libgda/gda-set.c | 20 ++--
libgda/gda-sql-builder.c | 132 ++++++++++++------------
libgda/gda-transaction-status.c | 6 +-
libgda/gda-tree-manager.c | 37 +++----
libgda/gda-tree-mgr-columns.c | 12 +-
libgda/gda-tree-mgr-label.c | 8 +-
libgda/gda-tree-mgr-schemas.c | 8 +-
libgda/gda-tree-mgr-select.c | 8 +-
libgda/gda-tree-mgr-tables.c | 10 +-
libgda/gda-tree-node.c | 50 +++++-----
libgda/gda-tree.c | 38 ++++----
libgda/gda-value.c | 206 +++++++++++++++++++-----------------
libgda/gda-xa-transaction.c | 47 ++++----
24 files changed, 557 insertions(+), 526 deletions(-)
---
diff --git a/libgda/gda-data-proxy.c b/libgda/gda-data-proxy.c
index ad95571..58f8d99 100644
--- a/libgda/gda-data-proxy.c
+++ b/libgda/gda-data-proxy.c
@@ -2180,8 +2180,9 @@ gda_data_proxy_get_n_modified_rows (GdaDataProxy *proxy)
* @proxy: a #GdaDataProxy object
* @sample_size: the requested size of a chunk, or 0
*
- * Sets the size of each chunk of fata to display: the maximum number of rows which
- * can be displayed at a time. The default value is arbitrary 300 as it is big enough to
+ * Sets the size of each chunk of data to display: the maximum number of rows which
+ * can be "displayed" at a time (the maximum number of rows which @proxy pretends to have).
+ * The default value is arbitrary 300 as it is big enough to
* be able to display quite a lot of data, but small enough to avoid too much data
* displayed at the same time.
*
@@ -2189,7 +2190,7 @@ gda_data_proxy_get_n_modified_rows (GdaDataProxy *proxy)
* regardless of the current chunk of data, and the modified rows which are not visible
* when the displayed chunk of data changes are still held as modified rows.
*
- * To remove the chunking of the data to display, simply pass @sample_size the 0 value.
+ * To remove the chunking of the data to display, simply pass @sample_size the %0 value.
*/
void
gda_data_proxy_set_sample_size (GdaDataProxy *proxy, gint sample_size)
diff --git a/libgda/gda-meta-store.c b/libgda/gda-meta-store.c
index a390663..ca9da76 100644
--- a/libgda/gda-meta-store.c
+++ b/libgda/gda-meta-store.c
@@ -1,6 +1,6 @@
/* gda-meta-store.c
*
- * Copyright (C) 2008 - 2009 Vivien Malerba
+ * Copyright (C) 2008 - 2010 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -598,13 +598,13 @@ gda_meta_store_constructor (GType type,
}
/**
- * gda_meta_store_new_with_file
+ * gda_meta_store_new_with_file:
* @file_name: a file name
*
* Create a new #GdaMetaStore object using @file_name as its internal
* database
*
- * Returns: the newly created object, or %NULL if an error occurred
+ * Returns: (transfer full): the newly created object, or %NULL if an error occurred
*/
GdaMetaStore *
gda_meta_store_new_with_file (const gchar *file_name)
@@ -628,12 +628,12 @@ gda_meta_store_new_with_file (const gchar *file_name)
}
/**
- * gda_meta_store_new
+ * gda_meta_store_new:
* @cnc_string: a connection string, or %NULL for an in-memory internal database
*
* Create a new #GdaMetaStore object.
*
- * Returns: the newly created object, or %NULL if an error occurred
+ * Returns: (transfer full): the newly created object, or %NULL if an error occurred
*/
GdaMetaStore *
gda_meta_store_new (const gchar *cnc_string)
@@ -810,7 +810,7 @@ gda_meta_store_get_property (GObject *object,
}
/**
- * gda_meta_store_set_identifiers_style
+ * gda_meta_store_set_identifiers_style:
* @store: a #GdaMetaStore object
* @style: a style
*
@@ -827,9 +827,9 @@ gda_meta_store_set_identifiers_style (GdaMetaStore *store, GdaSqlIdentifierStyle
}
/**
- * gda_meta_store_set_reserved_keywords_func
+ * gda_meta_store_set_reserved_keywords_func:
* @store: a #GdaMetaStore object
- * @func: a #GdaSqlReservedKeywordsFunc function, or %NULL
+ * @func: (allow-none): a #GdaSqlReservedKeywordsFunc function, or %NULL
*
* Specifies a function which @store will use to determine if a keyword is an SQL reserved
* keyword or not.
@@ -2186,7 +2186,7 @@ handle_schema_version (GdaMetaStore *store, gboolean *schema_present, GError **e
}
/**
- * gda_meta_store_get_version
+ * gda_meta_store_get_version:
* @store: a #GdaMetaStore object
*
* Get @store's internal schema's version
@@ -2202,7 +2202,7 @@ gda_meta_store_get_version (GdaMetaStore *store) {
}
/**
- * gda_meta_store_get_internal_connection
+ * gda_meta_store_get_internal_connection:
* @store: a #GdaMetaStore object
*
* Get a pointer to the #GdaConnection object internally used by @store to store
@@ -2212,7 +2212,7 @@ gda_meta_store_get_version (GdaMetaStore *store) {
* itself. The returned object is not owned by the caller (if you need to keep it, then use g_object_ref()).
* Do not close the connection.
*
- * Returns: a #GdaConnection, or %NULL
+ * Returns: (transfer none): a #GdaConnection, or %NULL
*/
GdaConnection *
gda_meta_store_get_internal_connection (GdaMetaStore *store) {
@@ -2223,7 +2223,7 @@ gda_meta_store_get_internal_connection (GdaMetaStore *store) {
}
/**
- * gda_meta_store_sql_identifier_quote
+ * gda_meta_store_sql_identifier_quote:
* @id: an SQL identifier
* @cnc: a #GdaConnection
*
@@ -2234,7 +2234,7 @@ gda_meta_store_get_internal_connection (GdaMetaStore *store) {
* gda_connection_get_meta_store_data(), gda_connection_get_meta_store_data_v() and
* gda_meta_store_extract().
*
- * Returns: a new string, to free with g_free() once not needed anymore
+ * Returns: (transfer full): a new string, to free with g_free() once not needed anymore
*
* Since: 4.0.3
*/
@@ -2250,10 +2250,10 @@ gda_meta_store_sql_identifier_quote (const gchar *id, GdaConnection *cnc)
}
/**
- * gda_meta_store_extract
+ * gda_meta_store_extract:
* @store: a #GdaMetaStore object
* @select_sql: a SELECT statement
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
* @...: a list of (variable name (gchar *), GValue *value) terminated with NULL, representing values for all the
* variables mentioned in @select_sql. If there is no variable then this part can be omitted.
*
@@ -2265,7 +2265,7 @@ gda_meta_store_sql_identifier_quote (const gchar *id, GdaConnection *cnc)
* SQL identifiers are represented in @store, see the
* <link linkend="information_schema:sql_identifiers">meta data section about SQL identifiers</link>.
*
- * Returns: a new #GdaDataModel, or %NULL if an error occurred
+ * Returns: (transfer full): a new #GdaDataModel, or %NULL if an error occurred
*/
GdaDataModel *
gda_meta_store_extract (GdaMetaStore *store, const gchar *select_sql, GError **error, ...)
@@ -2275,6 +2275,7 @@ gda_meta_store_extract (GdaMetaStore *store, const gchar *select_sql, GError **e
GdaSet *params = NULL;
g_return_val_if_fail (GDA_IS_META_STORE (store), NULL);
+ g_return_val_if_fail (select_sql, NULL);
if (store->priv->init_error) {
g_propagate_error (error, g_error_copy (store->priv->init_error));
@@ -2376,13 +2377,13 @@ static gboolean gda_meta_store_modify_v (GdaMetaStore *store, const gchar *table
gint nvalues, const gchar **value_names, const GValue **values);
/**
- * gda_meta_store_modify
+ * gda_meta_store_modify:
* @store: a #GdaMetaStore object
* @table_name: the name of the table to modify within @store
- * @new_data: a #GdaDataModel containing the new data to set in @table_name, or %NULL (treated as a data model
+ * @new_data: (allow-none): a #GdaDataModel containing the new data to set in @table_name, or %NULL (treated as a data model
* with no row at all)
- * @condition: SQL expression (which may contain variables) defining the rows which are being obsoleted by @new_data, or %NULL
- * @error: a place to store errors, or %NULL
+ * @condition: (allow-none): SQL expression (which may contain variables) defining the rows which are being obsoleted by @new_data, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
* @...: a list of (variable name (gchar *), GValue *value) terminated with NULL, representing values for all the
* variables mentioned in @condition.
*
@@ -2443,10 +2444,10 @@ gda_meta_store_modify (GdaMetaStore *store, const gchar *table_name,
}
/**
- * gda_meta_store_modify_with_context
+ * gda_meta_store_modify_with_context:
* @store: a #GdaMetaStore object
- * @context: a #GdaMetaContext context describing what to modify in @store
- * @new_data: a #GdaDataModel containing the new data to set in @table_name, or %NULL (treated as a data model
+ * @context: (transfer none): a #GdaMetaContext context describing what to modify in @store
+ * @new_data: (transfer none) (allow-none): a #GdaDataModel containing the new data to set in @table_name, or %NULL (treated as a data model
* with no row at all)
* @error: a place to store errors, or %NULL
*
@@ -2463,6 +2464,8 @@ gda_meta_store_modify_with_context (GdaMetaStore *store, GdaMetaContext *context
gint i;
gboolean retval;
+ g_return_val_if_fail (context, FALSE);
+
for (i = 0; i < context->size; i++) {
if (i == 0)
cond = g_string_new ("");
@@ -3044,9 +3047,9 @@ out:
}
/**
- * _gda_meta_store_begin_data_reset
+ * _gda_meta_store_begin_data_reset:
* @store: a #GdaMetaStore object
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* Sets @store in a mode where only the modifications completely overriding a table
* will be allowed, where no detailed modifications report is made and where the "suggest-update"
@@ -3088,9 +3091,9 @@ _gda_meta_store_begin_data_reset (GdaMetaStore *store, GError **error)
}
/**
- * _gda_meta_store_cancel_data_reset
+ * _gda_meta_store_cancel_data_reset:
* @store: a #GdaMetaStore object
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* Cancels any modification done since _gda_meta_store_begin_data_reset() was called.
*
@@ -3120,9 +3123,9 @@ _gda_meta_store_cancel_data_reset (GdaMetaStore *store, GError **error)
}
/**
- * _gda_meta_store_finish_data_reset
+ * _gda_meta_store_finish_data_reset:
* @store: a #GdaMetaStore object
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* Commits any modification done since _gda_meta_store_begin_data_reset() was called.
*
@@ -3174,7 +3177,7 @@ gda_meta_store_change_free (GdaMetaStoreChange *change) {
}
/**
- * gda_meta_store_create_modify_data_model
+ * gda_meta_store_create_modify_data_model:
* @store: a #GdaMetaStore object
* @table_name: the name of a table present in @store
*
@@ -3183,7 +3186,7 @@ gda_meta_store_change_free (GdaMetaStoreChange *change) {
*
* To be used by provider's implementation
*
- * Returns: a new #GdaDataModel
+ * Returns: (transfer full): a new #GdaDataModel
*/
GdaDataModel *
gda_meta_store_create_modify_data_model (GdaMetaStore *store, const gchar *table_name)
@@ -3229,15 +3232,14 @@ gda_meta_store_create_modify_data_model (GdaMetaStore *store, const gchar *table
}
/**
- * gda_meta_store_schema_get_all_tables
+ * gda_meta_store_schema_get_all_tables:
* @store: a #GdaMetaStore object
*
* Get an ordered list of the tables @store knows about. The tables are ordered in a way that tables dependencies
* are respected: if table B has a foreign key on table A, then table A will be listed before table B in the returned
* list.
*
- * Returns: a new list of tables names (as gchar*), the list must be freed when no longer needed,
- * but the strings present in the list must not be modified.
+ * Returns: (transfer container) (element type gchar*): a new list of tables names (as gchar*), the list must be freed when no longer needed, but the strings present in the list must not be modified.
*/
GSList *
gda_meta_store_schema_get_all_tables (GdaMetaStore *store)
@@ -3267,7 +3269,7 @@ gda_meta_store_schema_get_all_tables (GdaMetaStore *store)
}
/**
- * gda_meta_store_schema_get_depend_tables
+ * gda_meta_store_schema_get_depend_tables:
* @store: a #GdaMetaStore object
* @table_name: the name of the table for which all the dependencies must be listed
*
@@ -3277,8 +3279,7 @@ gda_meta_store_schema_get_all_tables (GdaMetaStore *store)
* are respected: if table B has a foreign key on table A, then table A will be listed before table B in the returned
* list.
*
- * Returns: a new list of tables names (as gchar*), the list must be freed when no longer needed,
- * but the strings present in the list must not be modified.
+ * Returns: (transfer container) (element type gchar*): a new list of tables names (as gchar*), the list must be freed when no longer needed, but the strings present in the list must not be modified.
*/
GSList *
gda_meta_store_schema_get_depend_tables (GdaMetaStore *store, const gchar *table_name)
@@ -3312,13 +3313,13 @@ gda_meta_store_schema_get_depend_tables (GdaMetaStore *store, const gchar *table
/**
- * gda_meta_store_schema_get_structure
+ * gda_meta_store_schema_get_structure:
* @store: a #GdaMetaStore object
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* Creates a new #GdaMetaStruct object representing @store's internal database structure.
*
- * Returns: a new #GdaMetaStruct object, or %NULL if an error occurred
+ * Returns: (transfer full): a new #GdaMetaStruct object, or %NULL if an error occurred
*/
GdaMetaStruct *
gda_meta_store_schema_get_structure (GdaMetaStore *store, GError **error)
@@ -3424,11 +3425,11 @@ gda_meta_store_schema_get_structure (GdaMetaStore *store, GError **error)
}
/**
- * gda_meta_store_get_attribute_value
+ * gda_meta_store_get_attribute_value:
* @store: a #GdaMetaStore object
* @att_name: name of the attribute to get
- * @att_value: the place to store the attribute value
- * @error: a place to store errors, or %NULL
+ * @att_value: (out): the place to store the attribute value
+ * @error: (allow-none): a place to store errors, or %NULL
*
* The #GdaMetaStore object maintains a list of (name,value) attributes (attributes names starting with a '_'
* character are for internal use only and cannot be altered). This method and the gda_meta_store_set_attribute_value()
@@ -3496,11 +3497,11 @@ gda_meta_store_get_attribute_value (GdaMetaStore *store, const gchar *att_name,
}
/**
- * gda_meta_store_set_attribute_value
+ * gda_meta_store_set_attribute_value:
* @store: a #GdaMetaStore object
* @att_name: name of the attribute to set
- * @att_value: value of the attribute to set, or %NULL to unset the attribute
- * @error: a place to store errors, or %NULL
+ * @att_value: (allow-none): value of the attribute to set, or %NULL to unset the attribute
+ * @error: (allow-none): a place to store errors, or %NULL
*
* Set the value of the attribute named @att_name to @att_value; see gda_meta_store_get_attribute_value() for
* more information.
@@ -3580,10 +3581,10 @@ gda_meta_store_set_attribute_value (GdaMetaStore *store, const gchar *att_name,
}
/**
- * gda_meta_store_schema_add_custom_object
+ * gda_meta_store_schema_add_custom_object:
* @store: a #GdaMetaStore object
* @xml_description: an XML description of the table or view to add to @store
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* The internal database used by @store can be 'augmented' with some user-defined database objects
* (such as tables or views). This method allows one to add a new database object.
@@ -3837,10 +3838,10 @@ gda_meta_store_schema_add_custom_object (GdaMetaStore *store, const gchar *xml_d
}
/**
- * gda_meta_store_schema_remove_custom_object
+ * gda_meta_store_schema_remove_custom_object:
* @store: a #GdaMetaStore object
* @obj_name: name of the custom object to remove
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* Removes the custom database object named @obj_name.
*
diff --git a/libgda/gda-meta-struct-io.c b/libgda/gda-meta-struct-io.c
index d966db8..146dd95 100644
--- a/libgda/gda-meta-struct-io.c
+++ b/libgda/gda-meta-struct-io.c
@@ -1,6 +1,6 @@
/* gda-meta-struct-io.c
*
- * Copyright (C) 2008 Vivien Malerba
+ * Copyright (C) 2008 - 2010 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -39,10 +39,14 @@ static GdaMetaDbObject *create_view_object (GdaMetaStruct *mstruct, const GValue
/**
- * gda_meta_struct_load_from_xml_file
- * @mstruct:
- * @xml_spec_file:
- * @error:
+ * gda_meta_struct_load_from_xml_file:
+ * @mstruct: a #GdaMetaStruct object
+ * @catalog: (allow-none): the catalog name, or %NULL
+ * @schema: (allow-none): the schema name, or %NULL
+ * @xml_spec_file: the specifications as the name of an XML file
+ * @error: (allow-none): a place to store errors, or %NULL
+ *
+ * Loads an XML description into @mstruct
*
* returns: TRUE if no error has occurred
*/
diff --git a/libgda/gda-meta-struct.c b/libgda/gda-meta-struct.c
index 6e8adbd..36fb4d0 100644
--- a/libgda/gda-meta-struct.c
+++ b/libgda/gda-meta-struct.c
@@ -1,6 +1,6 @@
/* gda-meta-struct.c
*
- * Copyright (C) 2008 Vivien Malerba
+ * Copyright (C) 2008 - 2010 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -158,7 +158,7 @@ gda_meta_struct_init (GdaMetaStruct *mstruct) {
/**
- * gda_meta_struct_new
+ * gda_meta_struct_new:
* @store: a #GdaMetaStore from which the new #GdaMetaStruct object will fetch information
* @features: the kind of extra information the new #GdaMetaStruct object will compute
*
@@ -166,7 +166,7 @@ gda_meta_struct_init (GdaMetaStruct *mstruct) {
* the more features, the more time it takes to run. Features such as table's columns, each column's attributes, etc
* are not optional and will always be computed.
*
- * Returns: the newly created #GdaMetaStruct object
+ * Returns: (transfer full): the newly created #GdaMetaStruct object
*/
GdaMetaStruct *
gda_meta_struct_new (GdaMetaStore *store, GdaMetaStructFeature features)
@@ -417,13 +417,13 @@ prepare_sql_identifier_for_compare (gchar *str)
}
/**
- * gda_meta_struct_complement
+ * gda_meta_struct_complement:
* @mstruct: a #GdaMetaStruct object
* @type: the type of object to add (which can be GDA_META_DB_UNKNOWN)
- * @catalog: the catalog the object belongs to (as a G_TYPE_STRING GValue), or %NULL
- * @schema: the schema the object belongs to (as a G_TYPE_STRING GValue), or %NULL
+ * @catalog: (allow-none): the catalog the object belongs to (as a G_TYPE_STRING GValue), or %NULL
+ * @schema: (allow-none): the schema the object belongs to (as a G_TYPE_STRING GValue), or %NULL
* @name: the object's name (as a G_TYPE_STRING GValue), not %NULL
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* Creates a new #GdaMetaDbObject structure in @mstruct to represent the database object (of type @type)
* which can be uniquely identified as @catalog schema @name.
@@ -445,7 +445,7 @@ prepare_sql_identifier_for_compare (gchar *str)
* For more information, see the <link linkend="information_schema:sql_identifiers">
* meta data section about SQL identifiers</link>.
*
- * Returns: the #GdaMetaDbObject corresponding to the database object if no error occurred, or %NULL
+ * Returns: (transfer none): the #GdaMetaDbObject corresponding to the database object if no error occurred, or %NULL
*/
GdaMetaDbObject *
gda_meta_struct_complement (GdaMetaStruct *mstruct, GdaMetaDbObjectType type,
@@ -1091,11 +1091,11 @@ array_type_to_sql (GdaMetaStore *store, const GValue *specific_name)
/**
- * gda_meta_struct_complement_schema
+ * gda_meta_struct_complement_schema:
* @mstruct: a #GdaMetaStruct object
- * @catalog: name of a catalog, or %NULL
- * @schema: name of a schema, or %NULL
- * @error: a place to store errors, or %NULL
+ * @catalog: (allow-none): name of a catalog, or %NULL
+ * @schema: (allow-none): name of a schema, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* This method is similar to gda_meta_struct_complement() but creates #GdaMetaDbObject for all the
* database object which are in the @schema schema (and in the @catalog catalog).
@@ -1293,9 +1293,9 @@ real_gda_meta_struct_complement_all (GdaMetaStruct *mstruct, gboolean default_on
}
/**
- * gda_meta_struct_complement_default
+ * gda_meta_struct_complement_default:
* @mstruct: a #GdaMetaStruct object
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* This method is similar to gda_meta_struct_complement() and gda_meta_struct_complement_all()
* but creates #GdaMetaDbObject for all the
@@ -1313,9 +1313,9 @@ gda_meta_struct_complement_default (GdaMetaStruct *mstruct, GError **error)
}
/**
- * gda_meta_struct_complement_all
+ * gda_meta_struct_complement_all:
* @mstruct: a #GdaMetaStruct object
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* This method is similar to gda_meta_struct_complement() and gda_meta_struct_complement_default()
* but creates #GdaMetaDbObject for all the database object.
@@ -1331,10 +1331,10 @@ gda_meta_struct_complement_all (GdaMetaStruct *mstruct, GError **error)
}
/**
- * gda_meta_struct_complement_depend
+ * gda_meta_struct_complement_depend:
* @mstruct: a #GdaMetaStruct object
* @dbo: a #GdaMetaDbObject part of @mstruct
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* This method is similar to gda_meta_struct_complement() but creates #GdaMetaDbObject for all the dependencies
* of @dbo.
@@ -1440,10 +1440,10 @@ db_object_sort_func (GdaMetaDbObject *dbo1, GdaMetaDbObject *dbo2)
}
/**
- * gda_meta_struct_sort_db_objects
+ * gda_meta_struct_sort_db_objects:
* @mstruct: a #GdaMetaStruct object
* @sort_type: the kind of sorting requested
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* Reorders the list of database objects within @mstruct in a way specified by @sort_type.
*
@@ -1543,14 +1543,13 @@ _meta_struct_get_db_object (GdaMetaStruct *mstruct, const GValue *catalog, const
}
/**
- * gda_meta_struct_get_all_db_objects
+ * gda_meta_struct_get_all_db_objects:
* @mstruct: a #GdaMetaStruct object
*
* Get a list of all the #GdaMetaDbObject structures representing database objects in @mstruct. Note that
* no #GdaMetaDbObject structure must not be modified.
*
- * Returns: a new #GSList list of pointers to #GdaMetaDbObject structures which must be destroyed after
- * usage using g_slist_free(). The individual #GdaMetaDbObject must not be modified.
+ * Returns: (transfer container): a new #GSList list of pointers to #GdaMetaDbObject structures which must be destroyed after usage using g_slist_free(). The individual #GdaMetaDbObject must not be modified.
*/
GSList *
gda_meta_struct_get_all_db_objects (GdaMetaStruct *mstruct)
@@ -1563,10 +1562,10 @@ gda_meta_struct_get_all_db_objects (GdaMetaStruct *mstruct)
}
/**
- * gda_meta_struct_get_db_object
+ * gda_meta_struct_get_db_object:
* @mstruct: a #GdaMetaStruct object
- * @catalog: the catalog the object belongs to (as a G_TYPE_STRING GValue), or %NULL
- * @schema: the schema the object belongs to (as a G_TYPE_STRING GValue), or %NULL
+ * @catalog: (allow-none): the catalog the object belongs to (as a G_TYPE_STRING GValue), or %NULL
+ * @schema: (allow-none): the schema the object belongs to (as a G_TYPE_STRING GValue), or %NULL
* @name: the object's name (as a G_TYPE_STRING GValue), not %NULL
*
* Tries to locate the #GdaMetaDbObject structure representing the database object named after
@@ -1575,7 +1574,7 @@ gda_meta_struct_get_all_db_objects (GdaMetaStruct *mstruct)
* If one or both of @catalog and @schema are %NULL, and more than one database object matches the name, then
* the return value is also %NULL.
*
- * Returns: the #GdaMetaDbObject or %NULL if not found
+ * Returns: (transfer none): the #GdaMetaDbObject or %NULL if not found
*/
GdaMetaDbObject *
gda_meta_struct_get_db_object (GdaMetaStruct *mstruct, const GValue *catalog, const GValue *schema, const GValue *name)
@@ -1614,7 +1613,7 @@ gda_meta_struct_get_db_object (GdaMetaStruct *mstruct, const GValue *catalog, co
*
* Tries to find the #GdaMetaTableColumn representing the column named @col_name in @table.
*
- * Returns: the #GdaMetaTableColumn or %NULL if not found
+ * Returns: (transfer none): the #GdaMetaTableColumn or %NULL if not found
*/
GdaMetaTableColumn *
gda_meta_struct_get_table_column (GdaMetaStruct *mstruct, GdaMetaTable *table, const GValue *col_name)
@@ -1636,14 +1635,14 @@ gda_meta_struct_get_table_column (GdaMetaStruct *mstruct, GdaMetaTable *table, c
}
/**
- * gda_meta_struct_dump_as_graph
+ * gda_meta_struct_dump_as_graph:
* @mstruct: a #GdaMetaStruct object
* @info: informs what kind of information to show in the resulting graph
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* Creates a new graph (in the GraphViz syntax) representation of @mstruct.
*
- * Returns: a new string, or %NULL if an error occurred.
+ * Returns: (transfer full): a new string, or %NULL if an error occurred.
*/
gchar *
gda_meta_struct_dump_as_graph (GdaMetaStruct *mstruct, GdaMetaGraphInfo info, GError **error)
@@ -2233,17 +2232,17 @@ copyerror:
}
/**
- * gda_meta_struct_add_db_object
+ * gda_meta_struct_add_db_object:
* @mstruct: a #GdaMetaStruct object
* @dbo: a #GdaMetaDbObject structure
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* Adds @dbo to the database objects known to @mstruct. In any case (whether an error occured or not)
* @dbo's responsibility is then transferred to @smtruct and should
* not be used after calling this function (it may have been destroyed). If you need a pointer to the #GdaMetaDbObject
* for a database object, use gda_meta_struct_get_db_object().
*
- * Returns: a pointer to the #GdaMetaDbObject used in @mstruct to represent the added database object (may be @dbo or not)
+ * Returns: (transfer none): a pointer to the #GdaMetaDbObject used in @mstruct to represent the added database object (may be @dbo or not)
*/
GdaMetaDbObject *
gda_meta_struct_add_db_object (GdaMetaStruct *mstruct, GdaMetaDbObject *dbo, GError **error)
@@ -2293,7 +2292,7 @@ gda_meta_struct_add_db_object (GdaMetaStruct *mstruct, GdaMetaDbObject *dbo, GEr
}
/**
- * gda_meta_table_column_get_attribute
+ * gda_meta_table_column_get_attribute:
* @tcol: a #GdaMetaTableColumn
* @attribute: attribute name as a string
*
@@ -2301,7 +2300,7 @@ gda_meta_struct_add_db_object (GdaMetaStruct *mstruct, GdaMetaDbObject *dbo, GEr
*
* Attributes can have any name, but Libgda proposes some default names, see <link linkend="libgda-40-Attributes-manager.synopsis">this section</link>.
*
- * Returns: a read-only #GValue, or %NULL if not attribute named @attribute has been set for @column
+ * Returns: (transfer none): a read-only #GValue, or %NULL if not attribute named @attribute has been set for @column
*/
const GValue *
gda_meta_table_column_get_attribute (GdaMetaTableColumn *tcol, const gchar *attribute)
@@ -2310,11 +2309,11 @@ gda_meta_table_column_get_attribute (GdaMetaTableColumn *tcol, const gchar *attr
}
/**
- * gda_meta_table_column_set_attribute
+ * gda_meta_table_column_set_attribute:
* @tcol: a #GdaMetaTableColumn
* @attribute: attribute name as a static string
- * @value: a #GValue, or %NULL
- * @destroy: function called when @attribute has to be freed, or %NULL
+ * @value: (allow-none): a #GValue, or %NULL
+ * @destroy: (allow-none): function called when @attribute has to be freed, or %NULL
*
* Set the value associated to a named attribute.
*
@@ -2339,7 +2338,7 @@ gda_meta_table_column_set_attribute (GdaMetaTableColumn *tcol, const gchar *attr
}
/**
- * gda_meta_table_column_foreach_attribute
+ * gda_meta_table_column_foreach_attribute:
* @tcol: a #GdaMetaTableColumn
* @func: a #GdaAttributesManagerFunc function
* @data: user data to be passed as last argument of @func each time it is called
diff --git a/libgda/gda-mutex.c b/libgda/gda-mutex.c
index 79889e8..37e31ba 100644
--- a/libgda/gda-mutex.c
+++ b/libgda/gda-mutex.c
@@ -36,13 +36,13 @@ struct _GdaMutex {
};
/**
- * gda_mutex_new
+ * gda_mutex_new:
*
* Creates a new #GdaMutex.
*
* Note: Unlike g_mutex_new(), this function will return %NULL if g_thread_init() has not been called yet.
*
- * Returns: a new #GdaMutex
+ * Returns: (transfer full): a new #GdaMutex
*/
GdaMutex*
gda_mutex_new ()
@@ -92,7 +92,7 @@ gda_mutex_new ()
}
/**
- * gda_mutex_lock
+ * gda_mutex_lock:
* @mutex: a #GdaMutex
*
* Locks @mutex. If @mutex is already locked by another thread, the current thread will block until @mutex is unlocked by the other thread.
@@ -131,7 +131,7 @@ gda_mutex_lock (GdaMutex *mutex)
}
/**
- * gda_mutex_trylock
+ * gda_mutex_trylock:
* @mutex: a #GdaMutex
*
* Tries to lock @mutex. If @mutex is already locked by another thread, it immediately returns FALSE.
@@ -172,7 +172,7 @@ gda_mutex_trylock (GdaMutex *mutex)
}
/**
- * gda_mutex_unlock
+ * gda_mutex_unlock:
* @mutex: a #GdaMutex
*
* Unlocks @mutex. If another thread is blocked in a gda_mutex_lock() call for @mutex, it wil
@@ -200,8 +200,8 @@ gda_mutex_unlock (GdaMutex *mutex)
}
/**
- * gda_mutex_free
- * @mutex: a #GdaMutex
+ * gda_mutex_free:
+ * @mutex: (transfer full): a #GdaMutex
*
* Destroys @mutex.
*/
diff --git a/libgda/gda-quark-list.c b/libgda/gda-quark-list.c
index 5a2d7ad..afcade3 100644
--- a/libgda/gda-quark-list.c
+++ b/libgda/gda-quark-list.c
@@ -1,5 +1,5 @@
/* GDA Common Library
- * Copyright (C) 1998 - 2008 The GNOME Foundation.
+ * Copyright (C) 1998 - 2010 The GNOME Foundation.
*
* Authors:
* Rodrigo Moya <rodrigo gnome-db org>
@@ -52,14 +52,16 @@ copy_hash_pair (gpointer key, gpointer value, gpointer user_data)
}
/**
- * gda_quark_list_new
+ * gda_quark_list_new:
*
* Creates a new #GdaQuarkList, which is a set of key->value pairs,
* very similar to GLib's GHashTable, but with the only purpose to
* make easier the parsing and creation of data source connection
* strings.
*
- * Returns: the newly created #GdaQuarkList.
+ * Returns: (transfer full): the newly created #GdaQuarkList.
+ *
+ * Free-function: gda_quark_list_free
*/
GdaQuarkList *
gda_quark_list_new (void)
@@ -73,7 +75,7 @@ gda_quark_list_new (void)
}
/**
- * gda_quark_list_new_from_string
+ * gda_quark_list_new_from_string:
* @string: a string.
*
* Creates a new #GdaQuarkList given a string.
@@ -86,7 +88,9 @@ gda_quark_list_new (void)
* "DB_NAME=notes;USERNAME=al%%20fred" string will specify a username as "al fred"). If this formalism
* is not respected, then some unexpected results may occur.
*
- * Returns: the newly created #GdaQuarkList.
+ * Returns: (transfer full): the newly created #GdaQuarkList.
+ *
+ * Free-function: gda_quark_list_free
*/
GdaQuarkList *
gda_quark_list_new_from_string (const gchar *string)
@@ -100,7 +104,7 @@ gda_quark_list_new_from_string (const gchar *string)
}
/**
- * gda_quark_list_clear
+ * gda_quark_list_clear:
* @qlist: a #GdaQuarkList.
*
* Removes all strings in the given #GdaQuarkList.
@@ -114,7 +118,7 @@ gda_quark_list_clear (GdaQuarkList *qlist)
}
/**
- * gda_quark_list_free
+ * gda_quark_list_free:
* @qlist: a #GdaQuarkList.
*
* Releases all memory occupied by the given #GdaQuarkList.
diff --git a/libgda/gda-repetitive-statement.c b/libgda/gda-repetitive-statement.c
index 3f0008c..f5974c9 100644
--- a/libgda/gda-repetitive-statement.c
+++ b/libgda/gda-repetitive-statement.c
@@ -1,6 +1,10 @@
/* GDA library
*
- * Copyright (C) Daniel Espinosa Ortiz 2008 <esodan gmail com>
+ * Copyright (C) 2008 - 2010 The GNOME Foundation.
+ *
+ * AUTHORS:
+ * Daniel Espinosa Ortiz 2008 <esodan gmail com>
+ * Vivien Malerba <malerba gnome-db org>
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -121,7 +125,7 @@ gda_repetitive_statement_class_init (GdaRepetitiveStatementClass *klass)
}
/**
- * gda_repetitive_statement_new
+ * gda_repetitive_statement_new:
* @stmt: a #GdaStatement object
*
* Creates a new #GdaRepetitiveStatement object which, when executed, will execute @stmt once for all
@@ -144,17 +148,17 @@ gda_repetitive_statement_new (GdaStatement *stmt)
}
/**
- * gda_repetitive_statement_get_template_set
+ * gda_repetitive_statement_get_template_set:
* @rstmt: a #GdaRepetitiveStatement object
* @set: a place to store the returned template set
- * @error: a place to store error, or %NULL
+ * @error: (allow-none): a place to store error, or %NULL
*
* Gets a new #GdaSet object with the parameters used by the template statement in the
* @rstmt object.
*
* Use this object with gda_repetitive_statement_append_set().
*
- * Returns: TRUE on success, FALSE on error
+ * Returns: %TRUE on success, %FALSE on error
*
* Since: 4.2
*/
@@ -169,7 +173,7 @@ gda_repetitive_statement_get_template_set (GdaRepetitiveStatement *rstmt, GdaSet
}
/**
- * gda_repetitive_statement_append_set
+ * gda_repetitive_statement_append_set:
* @rstmt: a #GdaRepetitiveStatement object
* @values: a #GdaSet object with the values to be used
* @make_copy: %TRUE if @values is copied, and %FALSE if @values is only ref'ed
@@ -204,12 +208,12 @@ gda_repetitive_statement_append_set (GdaRepetitiveStatement *rstmt, GdaSet *valu
}
/**
- * gda_repetitive_statement_get_all_sets
+ * gda_repetitive_statement_get_all_sets:
* @rstmt: a #GdaRepetitiveStatement object
*
* Get all the values sets which will have been added using gda_repetitive_statement_append_set().
*
- * Returns: a new #GSList of #GdaSet objects (free with g_slist_free()).
+ * Returns: (transfer container) (element-type GdaSet): a new #GSList of #GdaSet objects (free with g_slist_free()).
*
* Since: 4.2
*/
@@ -220,5 +224,5 @@ gda_repetitive_statement_get_all_sets (GdaRepetitiveStatement *rstmt)
priv = GDA_REPETITIVE_STATEMENT_PRIVATE (rstmt);
- return g_slist_reverse (priv->values_sets);
+ return g_slist_copy (g_slist_reverse (priv->values_sets));
}
diff --git a/libgda/gda-row.c b/libgda/gda-row.c
index fcf7d2e..c2ecd03 100644
--- a/libgda/gda-row.c
+++ b/libgda/gda-row.c
@@ -1,5 +1,5 @@
/* GDA library
- * Copyright (C) 1998 - 2008 The GNOME Foundation.
+ * Copyright (C) 1998 - 2010 The GNOME Foundation.
*
* AUTHORS:
* Rodrigo Moya <rodrigo gnome-db org>
@@ -193,7 +193,7 @@ gda_row_get_type (void)
}
/**
- * gda_row_new
+ * gda_row_new:
* @count: number of #GValue in the new #GdaRow.
*
* Creates a #GdaRow which can hold @count #GValue values.
@@ -209,7 +209,7 @@ gda_row_new (gint count)
}
/**
- * gda_row_get_value
+ * gda_row_get_value:
* @row: a #GdaRow
* @num: field index.
*
@@ -218,7 +218,7 @@ gda_row_new (gint count)
* This is a pointer to the internal array of values. Don't try to free
* or modify it (modifying is reserved to database provider's implementations).
*
- * Returns: a pointer to the #GValue in the position @num of @row.
+ * Returns: (transfer none): a pointer to the #GValue in the position @num of @row.
*/
GValue *
gda_row_get_value (GdaRow *row, gint num)
@@ -230,7 +230,7 @@ gda_row_get_value (GdaRow *row, gint num)
}
/**
- * gda_row_invalidate_value
+ * gda_row_invalidate_value:
* @row: a #GdaRow
* @value: a #GValue belonging to @row (obtained with gda_row_get_value()).
*
@@ -245,7 +245,7 @@ gda_row_invalidate_value (GdaRow *row, GValue *value)
}
/**
- * gda_row_value_is_valid
+ * gda_row_value_is_valid:
* @row: a #GdaRow.
* @value: a #GValue belonging to @row (obtained with gda_row_get_value()).
*
@@ -253,7 +253,7 @@ gda_row_invalidate_value (GdaRow *row, GValue *value)
* This method is mainly used by database
* providers' implementations to report any error while reading a value from the database.
*
- * Returns: TRUE if @value is valid
+ * Returns: %TRUE if @value is valid
*/
gboolean
gda_row_value_is_valid (GdaRow *row, GValue *value)
@@ -262,7 +262,7 @@ gda_row_value_is_valid (GdaRow *row, GValue *value)
}
/**
- * gda_row_get_length
+ * gda_row_get_length:
* @row: a #GdaRow.
*
* Returns: the number of columns that the @row has.
diff --git a/libgda/gda-server-operation.c b/libgda/gda-server-operation.c
index 1091c5a..188450f 100644
--- a/libgda/gda-server-operation.c
+++ b/libgda/gda-server-operation.c
@@ -1,5 +1,5 @@
/* GDA library
- * Copyright (C) 2006 - 2009 The GNOME Foundation.
+ * Copyright (C) 2006 - 2010 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -1013,7 +1013,7 @@ _gda_server_operation_new_from_string (GdaServerOperationType op_type,
/**
- * gda_server_operation_new
+ * gda_server_operation_new:
* @op_type: type of operation
* @xml_file: a file which has the specifications for the GdaServerOperation object to create
*
@@ -1051,7 +1051,7 @@ gda_server_operation_new (GdaServerOperationType op_type, const gchar *xml_file)
}
/**
- * gda_server_operation_get_node_info
+ * gda_server_operation_get_node_info:
* @op: a #GdaServerOperation object
* @path_format: a complete path to a node (starting with "/") as a format string, similar to g_strdup_printf()'s argument
* @...: the arguments to insert into the format string
@@ -1059,7 +1059,7 @@ gda_server_operation_new (GdaServerOperationType op_type, const gchar *xml_file)
* Get information about the node identified by @path. The returned #GdaServerOperationNode structure can be
* copied but not modified; it may change or cease to exist if @op changes
*
- * Returns: a #GdaServerOperationNode structure, or %NULL if the node was not found
+ * Returns: (transfer none): a #GdaServerOperationNode structure, or %NULL if the node was not found
*/
GdaServerOperationNode *
gda_server_operation_get_node_info (GdaServerOperation *op, const gchar *path_format, ...)
@@ -1169,7 +1169,7 @@ gda_server_operation_get_node_info (GdaServerOperation *op, const gchar *path_fo
}
/**
- * gda_server_operation_get_op_type
+ * gda_server_operation_get_op_type:
* @op: a #GdaServerOperation object
*
* Get the type of operation @op is for
@@ -1186,12 +1186,12 @@ gda_server_operation_get_op_type (GdaServerOperation *op)
}
/**
- * gda_server_operation_op_type_to_string
+ * gda_server_operation_op_type_to_string:
* @type: a #GdaServerOperationType value
*
* Get a string version of @type
*
- * Returns: a non %NULL string (do not free or modify)
+ * Returns: (transfer none): a non %NULL string (do not free or modify)
*/
const gchar *
gda_server_operation_op_type_to_string (GdaServerOperationType type)
@@ -1237,7 +1237,7 @@ gda_server_operation_op_type_to_string (GdaServerOperationType type)
}
/**
- * gda_server_operation_string_to_op_type
+ * gda_server_operation_string_to_op_type:
* @str: a string
*
* Performs the reverse of gda_server_operation_op_type_to_string()
@@ -1292,15 +1292,15 @@ gda_server_operation_string_to_op_type (const gchar *str)
static gboolean node_save (GdaServerOperation *op, Node *opnode, xmlNodePtr parent);
/**
- * gda_server_operation_save_data_to_xml
+ * gda_server_operation_save_data_to_xml:
* @op: a #GdaServerOperation object
- * @error: a place to store errors or %NULL
+ * @error: (allow-none): a place to store errors or %NULL
*
* Creates a new #xmlNodePtr tree which can be used to save the #op object. This
* XML structure can then be saved to disk if necessary. Use xmlFreeNode to free
* the associated memory when not needed anymore.
*
- * Returns: a new #xmlNodePtr structure, or %NULL
+ * Returns: (transfer full): a new #xmlNodePtr structure, or %NULL
*/
xmlNodePtr
gda_server_operation_save_data_to_xml (GdaServerOperation *op, GError **error)
@@ -1413,10 +1413,10 @@ node_save (GdaServerOperation *op, Node *opnode, xmlNodePtr parent)
}
/**
- * gda_server_operation_load_data_from_xml
+ * gda_server_operation_load_data_from_xml:
* @op: a #GdaServerOperation object
* @node: a #xmlNodePtr
- * @error: a place to store errors or %NULL
+ * @error: (allow-none): a place to store errors or %NULL
*
* Loads the contents of @node into @op. The XML tree passed through the @node
* argument must correspond to an XML tree saved using gda_server_operation_save_data_to_xml().
@@ -1577,12 +1577,12 @@ gda_server_operation_load_data_from_xml (GdaServerOperation *op, xmlNodePtr node
}
/**
- * gda_server_operation_get_root_nodes
+ * gda_server_operation_get_root_nodes:
* @op: a #GdaServerOperation object
*
* Get an array of strings containing the paths of nodes situated at the root of @op.
*
- * Returns: a new array, which must be freed with g_strfreev().
+ * Returns: (transfer full): a new array, which must be freed with g_strfreev().
*/
gchar**
gda_server_operation_get_root_nodes (GdaServerOperation *op)
@@ -1602,10 +1602,10 @@ gda_server_operation_get_root_nodes (GdaServerOperation *op)
}
/**
- * gda_server_operation_get_node_type
+ * gda_server_operation_get_node_type:
* @op: a #GdaServerOperation object
* @path: a complete path to a node (starting with "/")
- * @status: a place to store the status of the node, or %NULL
+ * @status: (allow-none): a place to store the status of the node, or %NULL
*
* Convenience function to get the type of a node.
*
@@ -1630,13 +1630,13 @@ gda_server_operation_get_node_type (GdaServerOperation *op, const gchar *path,
}
/**
- * gda_server_operation_get_node_parent
+ * gda_server_operation_get_node_parent:
* @op: a #GdaServerOperation object
* @path: a complete path to a node (starting with "/")
*
* Get the complete path to the parent of the node defined by @path
*
- * Returns: a new string or %NULL if the node does not have any parent or does not exist.
+ * Returns: (transfer full): a new string or %NULL if the node does not have any parent or does not exist.
*/
gchar *
gda_server_operation_get_node_parent (GdaServerOperation *op, const gchar *path)
@@ -1671,13 +1671,13 @@ gda_server_operation_get_node_parent (GdaServerOperation *op, const gchar *path)
}
/**
- * gda_server_operation_get_node_path_portion
+ * gda_server_operation_get_node_path_portion:
* @op: a #GdaServerOperation object
* @path: a complete path to a node (starting with "/")
*
* Get the last part of @path
*
- * Returns: a new string, or %NULL if an error occurred
+ * Returns: (transfer full): a new string, or %NULL if an error occurred
*/
gchar *
gda_server_operation_get_node_path_portion (GdaServerOperation *op, const gchar *path)
@@ -1712,14 +1712,14 @@ gda_server_operation_get_node_path_portion (GdaServerOperation *op, const gchar
}
/**
- * gda_server_operation_get_sequence_item_names
+ * gda_server_operation_get_sequence_item_names:
* @op: a #GdaServerOperation object
* @path: a complete path to a sequence node (starting with "/")
*
* Fetch the contents of a sequence. @path can describe either a sequence (for example "/SEQNAME") or an item in a sequence
* (for example "/SEQNAME/3")
*
- * Returns: a array of strings containing the complete paths of the nodes contained at @path (free with g_strfreev())
+ * Returns: (transfer full): a array of strings containing the complete paths of the nodes contained at @path (free with g_strfreev())
*/
gchar **
gda_server_operation_get_sequence_item_names (GdaServerOperation *op, const gchar *path)
@@ -1750,11 +1750,11 @@ gda_server_operation_get_sequence_item_names (GdaServerOperation *op, const gcha
}
/**
- * gda_server_operation_get_sequence_name
+ * gda_server_operation_get_sequence_name:
* @op: a #GdaServerOperation object
* @path: a complete path to a sequence node (starting with "/")
*
- * Returns: the name of the sequence at @path
+ * Returns: (transfer none): the name of the sequence at @path
*/
const gchar *
gda_server_operation_get_sequence_name (GdaServerOperation *op, const gchar *path)
@@ -1772,7 +1772,7 @@ gda_server_operation_get_sequence_name (GdaServerOperation *op, const gchar *pat
}
/**
- * gda_server_operation_get_sequence_size
+ * gda_server_operation_get_sequence_size:
* @op: a #GdaServerOperation object
* @path: a complete path to a sequence node (starting with "/")
*
@@ -1794,7 +1794,7 @@ gda_server_operation_get_sequence_size (GdaServerOperation *op, const gchar *pat
}
/**
- * gda_server_operation_get_sequence_max_size
+ * gda_server_operation_get_sequence_max_size:
* @op: a #GdaServerOperation object
* @path: a complete path to a sequence node (starting with "/")
*
@@ -1816,7 +1816,7 @@ gda_server_operation_get_sequence_max_size (GdaServerOperation *op, const gchar
}
/**
- * gda_server_operation_get_sequence_min_size
+ * gda_server_operation_get_sequence_min_size:
* @op: a #GdaServerOperation object
* @path: a complete path to a sequence node (starting with "/")
*
@@ -1863,7 +1863,7 @@ dump (GdaServerOperation *op)
#endif
/**
- * gda_server_operation_add_item_to_sequence
+ * gda_server_operation_add_item_to_sequence:
* @op: a #GdaServerOperation object
* @seq_path: the path to the sequence to which an item must be added (like "/SEQ_NAME" for instance)
*
@@ -1895,7 +1895,7 @@ gda_server_operation_add_item_to_sequence (GdaServerOperation *op, const gchar *
}
/**
- * gda_server_operation_del_item_from_sequence
+ * gda_server_operation_del_item_from_sequence:
* @op: a #GdaServerOperation object
* @item_path: the path to the sequence's item to remove (like "/SEQ_NAME/5" for instance)
*
@@ -2018,7 +2018,7 @@ real_gda_server_operation_get_value_at (GdaServerOperation *op, const gchar *pat
}
/**
- * gda_server_operation_get_value_at
+ * gda_server_operation_get_value_at:
* @op: a #GdaServerOperation object
* @path_format: a complete path to a node (starting with "/")
* @...: arguments to use with @path_format to make a complete path
@@ -2026,7 +2026,7 @@ real_gda_server_operation_get_value_at (GdaServerOperation *op, const gchar *pat
* Get the value for the node at the path formed using @path_format and ... (the rules are the same as
* for g_strdup_printf())
*
- * Returns: a constant #GValue if a value has been defined, or %NULL if the value is undefined or
+ * Returns: (transfer none): a constant #GValue if a value has been defined, or %NULL if the value is undefined or
* if the @path is not defined or @path does not hold any value.
*/
const GValue *
@@ -2051,7 +2051,7 @@ gda_server_operation_get_value_at (GdaServerOperation *op, const gchar *path_for
}
/**
- * gda_server_operation_get_sql_identifier_at
+ * gda_server_operation_get_sql_identifier_at:
* @op: a #GdaServerOperation object
* @cnc: a #GdaConnection, or %NULL
* @prov: a #GdaServerProvider, or %NULL
@@ -2063,7 +2063,7 @@ gda_server_operation_get_value_at (GdaServerOperation *op, const gchar *path_for
* and will correctly be quoted to be used with @cnc, or @prov if @cnc is %NULL (a generic quoting rule
* will be applied if both are %NULL).
*
- * Returns: a new string, or %NULL if the value is undefined or
+ * Returns: (transfer full): a new string, or %NULL if the value is undefined or
* if the @path is not defined or @path does not hold any value, or if the value held is not a string
* (in that last case a warning is shown).
*
@@ -2099,7 +2099,7 @@ gda_server_operation_get_sql_identifier_at (GdaServerOperation *op, GdaConnectio
}
/**
- * gda_server_operation_set_value_at
+ * gda_server_operation_set_value_at:
* @op: a #GdaServerOperation object
* @value: a string
* @error: a place to store errors or %NULL
@@ -2136,7 +2136,7 @@ gda_server_operation_get_sql_identifier_at (GdaServerOperation *op, GdaConnectio
* </para></listitem>
* </itemizedlist>
*
- * Returns: TRUE if no error occurred
+ * Returns: %TRUE if no error occurred
*/
gboolean
gda_server_operation_set_value_at (GdaServerOperation *op, const gchar *value, GError **error,
@@ -2287,7 +2287,7 @@ gda_server_operation_set_value_at (GdaServerOperation *op, const gchar *value, G
}
/**
- * gda_server_operation_is_valid
+ * gda_server_operation_is_valid:
* @op: a #GdaServerOperation widget
* @xml_file: an XML specification file (see gda_server_operation_new())
* @error: a place to store an error, or %NULL
@@ -2297,7 +2297,7 @@ gda_server_operation_set_value_at (GdaServerOperation *op, const gchar *value, G
* if @xml_file is not %NULL, the validity of @op is tested against that specification,
* and not against the current @op's specification.
*
- * Returns: TRUE if @op is valid
+ * Returns: %TRUE if @op is valid
*/
gboolean
gda_server_operation_is_valid (GdaServerOperation *op, const gchar *xml_file, GError **error)
diff --git a/libgda/gda-server-provider-extra.c b/libgda/gda-server-provider-extra.c
index a72bdc2..eb12be9 100644
--- a/libgda/gda-server-provider-extra.c
+++ b/libgda/gda-server-provider-extra.c
@@ -1,5 +1,5 @@
/* GDA common library
- * Copyright (C) 2005 - 2008 The GNOME Foundation.
+ * Copyright (C) 2005 - 2010 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -36,19 +36,19 @@
#include <libgda/handlers/gda-handler-type.h>
/**
- * gda_server_provider_internal_get_parser
+ * gda_server_provider_internal_get_parser:
* @prov: a #GdaServerProvider
*
* This is a factory method to get a unique instance of a #GdaSqlParser object
* for each #GdaServerProvider object
- * Don't unref() it.
+ * Don't unref it.
*
- * Returns: a #GdaSqlParser
+ * Returns: (transfer none): a #GdaSqlParser
*/
GdaSqlParser *
gda_server_provider_internal_get_parser (GdaServerProvider *prov)
{
-
+ g_return_val_if_fail (GDA_IS_SERVER_PROVIDER (prov), NULL);
if (prov->priv->parser)
return prov->priv->parser;
prov->priv->parser = gda_server_provider_create_parser (prov, NULL);
@@ -58,15 +58,15 @@ gda_server_provider_internal_get_parser (GdaServerProvider *prov)
}
/**
- * gda_server_provider_perform_operation_default
+ * gda_server_provider_perform_operation_default:
* @provider: a #GdaServerProvider object
- * @cnc: a #GdaConnection object which will be used to perform an action, or %NULL
+ * @cnc: (allow-none): a #GdaConnection object which will be used to perform an action, or %NULL
* @op: a #GdaServerOperation object
* @error: a place to store an error, or %NULL
*
* Performs the operation described by @op, using the SQL from the rendering of the operation
*
- * Returns: TRUE if no error occurred
+ * Returns: %TRUE if no error occurred
*/
gboolean
gda_server_provider_perform_operation_default (GdaServerProvider *provider, GdaConnection *cnc,
@@ -98,15 +98,15 @@ gda_server_provider_perform_operation_default (GdaServerProvider *provider, GdaC
}
/**
- * gda_server_provider_get_data_handler_default
+ * gda_server_provider_get_data_handler_default:
* @provider: a server provider.
- * @cnc: a #GdaConnection object, or %NULL
+ * @cnc: (allow-none): a #GdaConnection object, or %NULL
* @type: a #GType
* @dbms_type: a DBMS type definition
*
* Provides the implementation when the default Libgda's data handlers must be used
*
- * Returns: a #GdaDataHandler, or %NULL
+ * Returns: (transfer none): a #GdaDataHandler, or %NULL
*/
GdaDataHandler *
gda_server_provider_get_data_handler_default (GdaServerProvider *provider, GdaConnection *cnc,
@@ -206,9 +206,14 @@ param_to_null_foreach (GdaSqlAnyPart *part, gpointer data, GError **error)
}
/**
- * gda_select_alter_select_for_empty
+ * gda_select_alter_select_for_empty:
+ * @stmt: a SELECT #GdaStatement
+ * @error: (allow-none): a place to store errors, or %NULL
+ *
+ * Creates a new #GdaStatement, selecting the same data as @stmt, but which always returns an
+ * empty (no row) data model. This is use dy database providers' implementations.
*
- * Returns: a new #GdaStatement
+ * Returns: (transfer full): a new #GdaStatement
*/
GdaStatement *
gda_select_alter_select_for_empty (GdaStatement *stmt, GError **error)
@@ -255,8 +260,8 @@ gda_select_alter_select_for_empty (GdaStatement *stmt, GError **error)
}
/**
- * gda_server_provider_get_schema_nb_columns
- * @schema:
+ * gda_server_provider_get_schema_nb_columns:
+ * @schema: a #GdaConnectionSchema
*
* Returns: the number of columns the #GdaDataModel for the requested schema
* must have
@@ -468,13 +473,13 @@ schema_get_spec (GdaConnectionSchema schema)
}
/**
- * gda_server_provider_init_schema_model
+ * gda_server_provider_init_schema_model:
* @model: a #GdaDataModel
* @schema: a #GdaConnectionSchema
*
* Sets the column attributes of @model for the requested schema
*
- * Returns: TRUE if there was no error
+ * Returns: %TRUE if there was no error
*
* Deprecated: 4.2: This was a leftover from the pre 4.0 area
*/
@@ -504,14 +509,14 @@ gda_server_provider_init_schema_model (GdaDataModel *model, GdaConnectionSchema
}
/**
- * gda_server_provider_test_schema_model
+ * gda_server_provider_test_schema_model:
* @model: a #GdaDataModel to test
* @schema:
* @error:
*
* Test that the structure of @model is correct in regard with @schema
*
- * Returns: TRUE if @model has the correct structure
+ * Returns: %TRUE if @model has the correct structure
*
* Deprecated: 4.2: This was a leftover from the pre 4.0 area
*/
@@ -594,7 +599,7 @@ gda_server_provider_handler_declare (GdaServerProvider *prov, GdaDataHandler *dh
}
/**
- * gda_server_provider_find_file
+ * gda_server_provider_find_file:
* @prov: a #GdaServerProvider
* @inst_dir: directory where @prov is installed
* @filename: name of the file to find
@@ -602,7 +607,7 @@ gda_server_provider_handler_declare (GdaServerProvider *prov, GdaDataHandler *dh
* Finds the location of a @filename. This function should only be used by database provider's
* implementations
*
- * Returns: the complete path to @filename, or %NULL if not found
+ * Returns: (transfer full): the complete path to @filename, or %NULL if not found
*/
gchar *
gda_server_provider_find_file (GdaServerProvider *prov, const gchar *inst_dir, const gchar *filename)
@@ -636,7 +641,7 @@ gda_server_provider_find_file (GdaServerProvider *prov, const gchar *inst_dir, c
}
/**
- * gda_server_provider_load_file_contents
+ * gda_server_provider_load_file_contents:
* @inst_dir: directory where the database provider has been installed
* @data_dir: DATA directory to look for ($prefix/share)
* @filename: name of the file to load
@@ -645,7 +650,7 @@ gda_server_provider_find_file (GdaServerProvider *prov, const gchar *inst_dir, c
* This function should only be used by database provider's
* implementations
*
- * Returns: a new string containing @filename's contents, or %NULL if not found or if an error occurred
+ * Returns: (transfer full): a new string containing @filename's contents, or %NULL if not found or if an error occurred
*/
gchar *
gda_server_provider_load_file_contents (const gchar *inst_dir, const gchar *data_dir, const gchar *filename)
diff --git a/libgda/gda-server-provider.c b/libgda/gda-server-provider.c
index 8255e51..9ff0dfa 100644
--- a/libgda/gda-server-provider.c
+++ b/libgda/gda-server-provider.c
@@ -1,5 +1,5 @@
/* GDA library
- * Copyright (C) 1998 - 2008 The GNOME Foundation.
+ * Copyright (C) 1998 - 2010 The GNOME Foundation.
*
* AUTHORS:
* Rodrigo Moya <rodrigo gnome-db org>
@@ -250,12 +250,12 @@ gda_server_provider_get_property (GObject *object,
}
/**
- * gda_server_provider_get_version
+ * gda_server_provider_get_version:
* @provider: a #GdaServerProvider object.
*
* Get the version of the provider.
*
- * Returns: a string containing the version identification.
+ * Returns: (transfer none): a string containing the version identification.
*/
const gchar *
gda_server_provider_get_version (GdaServerProvider *provider)
@@ -267,12 +267,12 @@ gda_server_provider_get_version (GdaServerProvider *provider)
}
/**
- * gda_server_provider_get_name
+ * gda_server_provider_get_name:
* @provider: a #GdaServerProvider object.
*
* Get the name (identifier) of the provider
*
- * Returns: a string containing the provider's name
+ * Returns: (transfer none): a string containing the provider's name
*/
const gchar *
gda_server_provider_get_name (GdaServerProvider *provider)
@@ -284,13 +284,13 @@ gda_server_provider_get_name (GdaServerProvider *provider)
}
/**
- * gda_server_provider_get_server_version
+ * gda_server_provider_get_server_version:
* @provider: a #GdaServerProvider object.
* @cnc: a #GdaConnection object
*
* Get the version of the database to which the connection is opened.
*
- * Returns: a (read only) string, or %NULL if an error occurred
+ * Returns: (transfer none): a (read only) string, or %NULL if an error occurred
*/
const gchar *
gda_server_provider_get_server_version (GdaServerProvider *provider, GdaConnection *cnc)
@@ -308,16 +308,16 @@ gda_server_provider_get_server_version (GdaServerProvider *provider, GdaConnecti
}
/**
- * gda_server_provider_supports_operation
+ * gda_server_provider_supports_operation:
* @provider: a #GdaServerProvider object
- * @cnc: a #GdaConnection object which would be used to perform an action, or %NULL
+ * @cnc: (allow-none): a #GdaConnection object which would be used to perform an action, or %NULL
* @type: the type of operation requested
- * @options: a list of named parameters, or %NULL
+ * @options: (allow-none): a list of named parameters, or %NULL
*
* Tells if @provider supports the @type of operation on the @cnc connection, using the
* (optional) @options parameters.
*
- * Returns: TRUE if the operation is supported
+ * Returns: %TRUE if the operation is supported
*/
gboolean
gda_server_provider_supports_operation (GdaServerProvider *provider, GdaConnection *cnc,
@@ -437,12 +437,12 @@ static OpReq op_req_CREATE_USER [] = {
/**
- * gda_server_provider_create_operation
+ * gda_server_provider_create_operation:
* @provider: a #GdaServerProvider object
- * @cnc: a #GdaConnection object which will be used to perform an action, or %NULL
+ * @cnc: (allow-none): a #GdaConnection object which will be used to perform an action, or %NULL
* @type: the type of operation requested
* @options: an optional list of parameters
- * @error: a place to store an error, or %NULL
+ * @error: (allow-none): a place to store an error, or %NULL
*
* Creates a new #GdaServerOperation object which can be modified in order to perform the @type type of
* action. The @options can contain:
@@ -451,8 +451,7 @@ static OpReq op_req_CREATE_USER [] = {
* <listitem>named values which may change the contents of the GdaServerOperation, see <link linkend="gda-server-op-information-std">this section</link> for more information</listitem>
* </itemizedlist>
*
- * Returns: a new #GdaServerOperation object, or %NULL in the provider does not support the @type type
- * of operation or if an error occurred
+ * Returns: (transfer full): a new #GdaServerOperation object, or %NULL in the provider does not support the @type type of operation or if an error occurred
*/
GdaServerOperation *
gda_server_provider_create_operation (GdaServerProvider *provider, GdaConnection *cnc,
@@ -548,11 +547,11 @@ gda_server_provider_create_operation (GdaServerProvider *provider, GdaConnection
}
/**
- * gda_server_provider_render_operation
+ * gda_server_provider_render_operation:
* @provider: a #GdaServerProvider object
- * @cnc: a #GdaConnection object which will be used to render the action, or %NULL
+ * @cnc: (allow-none): a #GdaConnection object which will be used to render the action, or %NULL
* @op: a #GdaServerOperation object
- * @error: a place to store an error, or %NULL
+ * @error: (allow-none): a place to store an error, or %NULL
*
* Creates an SQL statement (possibly using some specific extensions of the DBMS) corresponding to the
* @op operation. Note that the returned string may actually contain more than one SQL statement.
@@ -560,7 +559,7 @@ gda_server_provider_create_operation (GdaServerProvider *provider, GdaConnection
* This function's purpose is mainly informative to get the actual SQL code which would be executed to perform
* the operation; to actually perform the operation, use gda_server_provider_perform_operation().
*
- * Returns: a new string, or %NULL if an error occurred or operation cannot be rendered as SQL.
+ * Returns: (transfer full): a new string, or %NULL if an error occurred or operation cannot be rendered as SQL.
*/
gchar *
gda_server_provider_render_operation (GdaServerProvider *provider, GdaConnection *cnc,
@@ -583,16 +582,16 @@ gda_server_provider_render_operation (GdaServerProvider *provider, GdaConnection
}
/**
- * gda_server_provider_perform_operation
+ * gda_server_provider_perform_operation:
* @provider: a #GdaServerProvider object
- * @cnc: a #GdaConnection object which will be used to perform the action, or %NULL
+ * @cnc: (allow-none): a #GdaConnection object which will be used to perform the action, or %NULL
* @op: a #GdaServerOperation object
- * @error: a place to store an error, or %NULL
+ * @error: (allow-none): a place to store an error, or %NULL
*
* Performs the operation described by @op. Note that @op is not destroyed by this method
* and can be reused.
*
- * Returns: TRUE if no error occurred
+ * Returns: %TRUE if no error occurred
*/
gboolean
gda_server_provider_perform_operation (GdaServerProvider *provider, GdaConnection *cnc,
@@ -626,14 +625,14 @@ gda_server_provider_perform_operation (GdaServerProvider *provider, GdaConnectio
}
/**
- * gda_server_provider_supports_feature
+ * gda_server_provider_supports_feature:
* @provider: a #GdaServerProvider object
- * @cnc: a #GdaConnection object, or %NULL
+ * @cnc: (allow-none): a #GdaConnection object, or %NULL
* @feature: #GdaConnectionFeature feature to test
*
* Tests if a feature is supported
*
- * Returns: TRUE if @feature is supported
+ * Returns: %TRUE if @feature is supported
*/
gboolean
gda_server_provider_supports_feature (GdaServerProvider *provider, GdaConnection *cnc,
@@ -676,14 +675,14 @@ gda_server_provider_supports_feature (GdaServerProvider *provider, GdaConnection
}
/**
- * gda_server_provider_get_data_handler_g_type
+ * gda_server_provider_get_data_handler_g_type:
* @provider: a server provider.
- * @cnc: a #GdaConnection object, or %NULL
+ * @cnc: (allow-none): a #GdaConnection object, or %NULL
* @for_type: a #GType
*
* Find a #GdaDataHandler object to manipulate data of type @for_type. The returned object must not be modified.
*
- * Returns: a #GdaDataHandler, or %NULL if the provider does not support the requested @for_type data type
+ * Returns: (transfer none): a #GdaDataHandler, or %NULL if the provider does not support the requested @for_type data type
*/
GdaDataHandler *
gda_server_provider_get_data_handler_g_type (GdaServerProvider *provider, GdaConnection *cnc, GType for_type)
@@ -704,14 +703,14 @@ gda_server_provider_get_data_handler_g_type (GdaServerProvider *provider, GdaCon
}
/**
- * gda_server_provider_get_data_handler_dbms
+ * gda_server_provider_get_data_handler_dbms:
* @provider: a server provider.
- * @cnc: a #GdaConnection object, or %NULL
+ * @cnc: (allow-none): a #GdaConnection object, or %NULL
* @for_type: a DBMS type definition
*
* Find a #GdaDataHandler object to manipulate data of type @for_type.
*
- * Returns: a #GdaDataHandler, or %NULL if the provider does not know about the @for_type type
+ * Returns: (transfer none): a #GdaDataHandler, or %NULL if the provider does not know about the @for_type type
*/
GdaDataHandler *
gda_server_provider_get_data_handler_dbms (GdaServerProvider *provider, GdaConnection *cnc, const gchar *for_type)
@@ -733,9 +732,9 @@ gda_server_provider_get_data_handler_dbms (GdaServerProvider *provider, GdaConne
}
/**
- * gda_server_provider_get_default_dbms_type
+ * gda_server_provider_get_default_dbms_type:
* @provider: a server provider.
- * @cnc: a #GdaConnection object or %NULL
+ * @cnc:(allow-none): a #GdaConnection object or %NULL
* @type: a #GType value type
*
* Get the name of the most common data type which has @type type.
@@ -744,7 +743,7 @@ gda_server_provider_get_data_handler_dbms (GdaServerProvider *provider, GdaConne
* there is no DBMS data type which could contain data of the @g_type type (for example %NULL may be
* returned if a DBMS has integers only up to 4 bytes and a G_TYPE_INT64 is requested).
*
- * Returns: the name of the DBMS type, or %NULL
+ * Returns: (transfer none): the name of the DBMS type, or %NULL
*/
const gchar *
gda_server_provider_get_default_dbms_type (GdaServerProvider *provider, GdaConnection *cnc, GType type)
@@ -766,12 +765,12 @@ gda_server_provider_get_default_dbms_type (GdaServerProvider *provider, GdaConne
/**
- * gda_server_provider_string_to_value
+ * gda_server_provider_string_to_value:
* @provider: a server provider.
- * @cnc: a #GdaConnection object, or %NULL
+ * @cnc: (allow-none): a #GdaConnection object, or %NULL
* @string: the SQL string to convert to a value
* @preferred_type: a #GType, or G_TYPE_INVALID
- * @dbms_type: place to get the actual database type used if the conversion succeeded, or %NULL
+ * @dbms_type: (allow-none): place to get the actual database type used if the conversion succeeded, or %NULL
*
* Use @provider to create a new #GValue from a single string representation.
*
@@ -788,7 +787,7 @@ gda_server_provider_get_default_dbms_type (GdaServerProvider *provider, GdaConne
* the database type used for the conversion if the conversion was successfull, or %NULL
* otherwise.
*
- * Returns: a new #GValue, or %NULL
+ * Returns: (transfer full): a new #GValue, or %NULL
*/
GValue *
gda_server_provider_string_to_value (GdaServerProvider *provider, GdaConnection *cnc, const gchar *string,
@@ -882,14 +881,14 @@ gda_server_provider_string_to_value (GdaServerProvider *provider, GdaConnection
/**
- * gda_server_provider_value_to_sql_string
+ * gda_server_provider_value_to_sql_string:
* @provider: a server provider.
- * @cnc: a #GdaConnection object, or %NULL
+ * @cnc: (allow-none): a #GdaConnection object, or %NULL
* @from: #GValue to convert from
*
* Produces a fully quoted and escaped string from a GValue
*
- * Returns: escaped and quoted value or NULL if not supported.
+ * Returns: (transfer full): escaped and quoted value or NULL if not supported.
*/
gchar *
gda_server_provider_value_to_sql_string (GdaServerProvider *provider,
@@ -914,15 +913,15 @@ gda_server_provider_value_to_sql_string (GdaServerProvider *provider,
}
/**
- * gda_server_provider_escape_string
+ * gda_server_provider_escape_string:
* @provider: a server provider.
- * @cnc: a #GdaConnection object, or %NULL
+ * @cnc: (allow-none): a #GdaConnection object, or %NULL
* @str: a string to escape
*
* Escapes @str for use within an SQL command (to avoid SQL injection attacks). Note that the returned value still needs
* to be enclosed in single quotes before being used in an SQL statement.
*
- * Returns: a new string suitable to use in SQL statements
+ * Returns: (transfer full): a new string suitable to use in SQL statements
*/
gchar *
gda_server_provider_escape_string (GdaServerProvider *provider, GdaConnection *cnc, const gchar *str)
@@ -949,14 +948,14 @@ gda_server_provider_escape_string (GdaServerProvider *provider, GdaConnection *c
}
/**
- * gda_server_provider_unescape_string
+ * gda_server_provider_unescape_string:
* @provider: a server provider.
- * @cnc: a #GdaConnection object, or %NULL
+ * @cnc: (allow-none): a #GdaConnection object, or %NULL
* @str: a string to escape
*
* Unescapes @str for use within an SQL command. This is the exact opposite of gda_server_provider_escape_string().
*
- * Returns: a new string
+ * Returns: (transfer full): a new string
*/
gchar *
gda_server_provider_unescape_string (GdaServerProvider *provider, GdaConnection *cnc, const gchar *str)
@@ -984,9 +983,9 @@ gda_server_provider_unescape_string (GdaServerProvider *provider, GdaConnection
/**
- * gda_server_provider_create_parser
+ * gda_server_provider_create_parser:
* @provider: a #GdaServerProvider provider object
- * @cnc: a #GdaConnection, or %NULL
+ * @cnc: (allow-none): a #GdaConnection, or %NULL
*
* Creates a new #GdaSqlParser object which is adapted to @provider (and possibly depending on
* @cnc for the actual database version).
@@ -994,7 +993,7 @@ gda_server_provider_unescape_string (GdaServerProvider *provider, GdaConnection
* If @prov does not have its own parser, then %NULL is returned, and a general SQL parser can be obtained
* using gda_sql_parser_new().
*
- * Returns: a new #GdaSqlParser object, or %NULL.
+ * Returns: (transfer full): a new #GdaSqlParser object, or %NULL.
*/
GdaSqlParser *
gda_server_provider_create_parser (GdaServerProvider *provider, GdaConnection *cnc)
diff --git a/libgda/gda-set.c b/libgda/gda-set.c
index 9d870f0..1028fa1 100644
--- a/libgda/gda-set.c
+++ b/libgda/gda-set.c
@@ -450,7 +450,7 @@ gda_set_new_read_only (GSList *holders)
*
* Creates a new #GdaSet object, copy of @set
*
- * Returns: a new #GdaSet object
+ * Returns: (transfer full): a new #GdaSet object
*/
GdaSet *
gda_set_copy (GdaSet *set)
@@ -483,7 +483,7 @@ gda_set_copy (GdaSet *set)
* to use an unsupported type will result in a warning, and the returned value holder holding a safe default
* value.
*
- * Returns: a new #GdaSet object
+ * Returns: (transfer full): a new #GdaSet object
*/
GdaSet *
gda_set_new_inline (gint nb, ...)
@@ -580,13 +580,13 @@ gda_set_new_inline (gint nb, ...)
/**
* gda_set_set_holder_value:
* @set: a #GdaSet object
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
* @holder_id: the ID of the holder to set the value
* @...: value, of the correct type, depending on the requested holder's type (not NULL)
*
* Set the value of the #GdaHolder which ID is @holder_id to a specified value
*
- * Returns: TRUE if no error occurred and the value was set correctly
+ * Returns: %TRUE if no error occurred and the value was set correctly
*/
gboolean
gda_set_set_holder_value (GdaSet *set, GError **error, const gchar *holder_id, ...)
@@ -665,7 +665,7 @@ gda_set_set_holder_value (GdaSet *set, GError **error, const gchar *holder_id, .
*
* Get the value of the #GdaHolder which ID is @holder_id
*
- * Returns: the requested GValue, or %NULL (see gda_holder_get_value())
+ * Returns: (transfer none): the requested GValue, or %NULL (see gda_holder_get_value())
*/
const GValue *
gda_set_get_holder_value (GdaSet *set, const gchar *holder_id)
@@ -708,12 +708,12 @@ xml_validity_error_func (void *ctx, const char *msg, ...)
/**
* gda_set_new_from_spec_string:
* @xml_spec: a string
- * @error: a place to store the error, or %NULL
+ * @error: (allow-none): a place to store the error, or %NULL
*
* Creates a new #GdaSet object from the @xml_spec
* specifications
*
- * Returns: a new object, or %NULL if an error occurred
+ * Returns: (transfer full): a new object, or %NULL if an error occurred
*/
GdaSet *
gda_set_new_from_spec_string (const gchar *xml_spec, GError **error)
@@ -800,12 +800,12 @@ gda_set_new_from_spec_string (const gchar *xml_spec, GError **error)
/**
* gda_set_new_from_spec_node:
* @xml_spec: a #xmlNodePtr for a <holders> tag
- * @error: a place to store the error, or %NULL
+ * @error: (allow-none): a place to store the error, or %NULL
*
* Creates a new #GdaSet object from the @xml_spec
* specifications
*
- * Returns: a new object, or %NULL if an error occurred
+ * Returns: (transfer full): a new object, or %NULL if an error occurred
*/
GdaSet *
gda_set_new_from_spec_node (xmlNodePtr xml_spec, GError **error)
@@ -1390,7 +1390,7 @@ set_remove_source (GdaSet *set, GdaSetSource *source)
/**
* gda_set_is_valid:
* @set: a #GdaSet object
- * @error: a place to store validation errors, or %NULL
+ * @error: (allow-none): a place to store validation errors, or %NULL
*
* This method tells if all @set's #GdaHolder objects are valid, and if
* they represent a valid combination of values, as defined by rules
diff --git a/libgda/gda-sql-builder.c b/libgda/gda-sql-builder.c
index a1fe8c5..80b6269 100644
--- a/libgda/gda-sql-builder.c
+++ b/libgda/gda-sql-builder.c
@@ -1,6 +1,6 @@
/* gda-sql-builder.c
*
- * Copyright (C) 2008 Vivien Malerba
+ * Copyright (C) 2008 - 2010 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -154,13 +154,13 @@ gda_sql_builder_init (GdaSqlBuilder *builder)
/**
- * gda_sql_builder_new
+ * gda_sql_builder_new:
* @stmt_type: the type of statement to build
*
* Create a new #GdaSqlBuilder object to build #GdaStatement or #GdaSqlStatement
* objects of type @stmt_type
*
- * Returns: the newly created object, or %NULL if an error occurred (such as unsupported
+ * Returns: (transfer full): the newly created object, or %NULL if an error occurred (such as unsupported
* statement type)
*
* Since: 4.2
@@ -315,13 +315,13 @@ use_part (SqlPart *p, GdaSqlAnyPart *parent)
}
/**
- * gda_sql_builder_get_statement
+ * gda_sql_builder_get_statement:
* @builder: a #GdaSqlBuilder object
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* Creates a new #GdaStatement statement from @builder's contents.
*
- * Returns: a new #GdaStatement object, or %NULL if an error occurred
+ * Returns: (transfer full): a new #GdaStatement object, or %NULL if an error occurred
*
* Since: 4.2
*/
@@ -341,7 +341,7 @@ gda_sql_builder_get_statement (GdaSqlBuilder *builder, GError **error)
}
/**
- * gda_sql_builder_get_sql_statement
+ * gda_sql_builder_get_sql_statement:
* @builder: a #GdaSqlBuilder object
* @copy_it: set to %TRUE to be able to reuse @builder
*
@@ -350,7 +350,7 @@ gda_sql_builder_get_statement (GdaSqlBuilder *builder, GError **error)
* The returned pointer belongs to @builder's internal representation.
* Use gda_sql_statement_copy() if you need to keep it.
*
- * Returns: a #GdaSqlStatement pointer
+ * Returns: (transfer none): a #GdaSqlStatement pointer
*
* Since: 4.2
*/
@@ -365,7 +365,7 @@ gda_sql_builder_get_sql_statement (GdaSqlBuilder *builder)
}
/**
- * gda_sql_builder_set_table
+ * gda_sql_builder_set_table:
* @builder: a #GdaSqlBuilder object
* @table_name: a table name
*
@@ -418,7 +418,7 @@ gda_sql_builder_set_table (GdaSqlBuilder *builder, const gchar *table_name)
}
/**
- * gda_sql_builder_set_where
+ * gda_sql_builder_set_where:
* @builder: a #GdaSqlBuilder object
* @cond_id: the ID of the expression to set as WHERE condition, or 0 to unset any previous WHERE condition
*
@@ -470,7 +470,7 @@ gda_sql_builder_set_where (GdaSqlBuilder *builder, GdaSqlBuilderId cond_id)
}
/**
- * gda_sql_builder_select_add_field
+ * gda_sql_builder_select_add_field:
* @builder: a #GdaSqlBuilder object
* @field_name: a field name
* @table_name: a table name, or %NULL
@@ -482,7 +482,7 @@ gda_sql_builder_set_where (GdaSqlBuilder *builder, GdaSqlBuilderId cond_id)
*
* For non-SELECT statements, see gda_sql_builder_add_field_id().
*
- * Returns: the ID of the added field, or 0 if there was an error
+ * Returns: the ID of the added field, or %0 if there was an error
*
* Since: 4.2
*/
@@ -590,7 +590,7 @@ create_typed_value (GType type, va_list *ap)
}
/**
- * gda_sql_builder_add_field_value
+ * gda_sql_builder_add_field_value:
* @builder: a #GdaSqlBuilder object
* @field_name: a field name
* @type: the GType of the following argument
@@ -635,7 +635,7 @@ gda_sql_builder_add_field_value (GdaSqlBuilder *builder, const gchar *field_name
}
/**
- * gda_sql_builder_add_field_value_as_gvalue
+ * gda_sql_builder_add_field_value_as_gvalue:
* @builder: a #GdaSqlBuilder object
* @field_name: a field name
* @value: value to set the field to, or %NULL or a GDA_TYPE_NULL value to represent an SQL NULL
@@ -667,7 +667,7 @@ gda_sql_builder_add_field_value_as_gvalue (GdaSqlBuilder *builder, const gchar *
}
/**
- * gda_sql_builder_add_field_value_id
+ * gda_sql_builder_add_field_value_id:
* @builder: a #GdaSqlBuilder object
* @field_id: the ID of the field's name or definition
* @value_id: the ID of the value to set the field to, or %0
@@ -784,7 +784,7 @@ gda_sql_builder_add_field_value_id (GdaSqlBuilder *builder, GdaSqlBuilderId fiel
}
/**
- * gda_sql_builder_add_expr_value
+ * gda_sql_builder_add_expr_value:
* @builder: a #GdaSqlBuilder object
* @dh: a #GdaDataHandler to use, or %NULL
* @value: value to set the expression to, or %NULL or a GDA_TYPE_NULL value to represent an SQL NULL
@@ -794,7 +794,7 @@ gda_sql_builder_add_field_value_id (GdaSqlBuilder *builder, GdaSqlBuilderId fiel
* The new expression will contain the value passed as the @value argument. It is possible to
* customize how the value has to be interpreted by passing a specific #GdaDataHandler object as @dh.
*
- * Returns: the ID of the new expression, or 0 if there was an error
+ * Returns: the ID of the new expression, or %0 if there was an error
*
* Since: 4.2
*/
@@ -840,7 +840,7 @@ gda_sql_builder_add_expr_value (GdaSqlBuilder *builder, GdaDataHandler *dh, cons
}
/**
- * gda_sql_builder_add_expr
+ * gda_sql_builder_add_expr:
* @builder: a #GdaSqlBuilder object
* @dh: a #GdaDataHandler to use, or %NULL
* @type: the GType of the following argument
@@ -868,7 +868,7 @@ id = gda_sql_builder_add_expr (b, NULL, G_TYPE_INT, 25);
* 25
* </programlisting>
*
- * Returns: the ID of the new expression, or 0 if there was an error
+ * Returns: the ID of the new expression, or %0 if there was an error
*
* Since: 4.2
*/
@@ -896,7 +896,7 @@ gda_sql_builder_add_expr (GdaSqlBuilder *builder, GdaDataHandler *dh, GType type
}
/**
- * gda_sql_builder_add_id
+ * gda_sql_builder_add_id:
* @builder: a #GdaSqlBuilder object
* @string: a string
*
@@ -922,7 +922,7 @@ gda_sql_builder_add_expr (GdaSqlBuilder *builder, GdaDataHandler *dh, GType type
*
* For fields, see gda_sql_builder_add_field_id().
*
- * Returns: the ID of the new expression, or 0 if there was an error
+ * Returns: the ID of the new expression, or %0 if there was an error
*
* Since: 4.2
*/
@@ -944,10 +944,10 @@ gda_sql_builder_add_id (GdaSqlBuilder *builder, const gchar *string)
}
/**
- * gda_sql_builder_add_field_id
+ * gda_sql_builder_add_field_id:
* @builder: a #GdaSqlBuilder object
* @field_name: a field name
- * @table_name: a table name, or %NULL
+ * @table_name: (allow-null): a table name, or %NULL
*
* Defines an expression representing a field in @builder,
* which may be reused to build other parts of a statement,
@@ -958,7 +958,7 @@ gda_sql_builder_add_id (GdaSqlBuilder *builder, const gchar *string)
*
* For SELECT queries, see gda_sql_builder_select_add_field().
*
- * Returns: the ID of the new expression, or 0 if there was an error
+ * Returns: the ID of the new expression, or %0 if there was an error
*
* Since: 4.2
*/
@@ -980,7 +980,7 @@ gda_sql_builder_add_field_id (GdaSqlBuilder *builder, const gchar *field_name, c
}
/**
- * gda_sql_builder_add_param
+ * gda_sql_builder_add_param:
* @builder: a #GdaSqlBuilder object
* @param_name: parameter's name
* @type: parameter's type
@@ -1000,7 +1000,7 @@ gda_sql_builder_add_field_id (GdaSqlBuilder *builder, const gchar *field_name, c
* ]]>
* </programlisting>
*
- * Returns: the ID of the new expression, or 0 if there was an error
+ * Returns: the ID of the new expression, or %0 if there was an error
*
* Since: 4.2
*/
@@ -1023,7 +1023,7 @@ gda_sql_builder_add_param (GdaSqlBuilder *builder, const gchar *param_name, GTyp
}
/**
- * gda_sql_builder_add_cond
+ * gda_sql_builder_add_cond:
* @builder: a #GdaSqlBuilder object
* @op: type of condition
* @op1: the ID of the 1st argument (not 0)
@@ -1032,7 +1032,7 @@ gda_sql_builder_add_param (GdaSqlBuilder *builder, const gchar *param_name, GTyp
*
* Builds a new expression which reprenents a condition (or operation).
*
- * Returns: the ID of the new expression, or 0 if there was an error
+ * Returns: the ID of the new expression, or %0 if there was an error
*
* Since: 4.2
*/
@@ -1067,11 +1067,11 @@ gda_sql_builder_add_cond (GdaSqlBuilder *builder, GdaSqlOperatorType op, GdaSqlB
}
/**
- * gda_sql_builder_add_cond_v
+ * gda_sql_builder_add_cond_v:
* @builder: a #GdaSqlBuilder object
* @op: type of condition
- * @op_ids: an array of ID for the arguments (not %0)
- * @ops_ids_size: size of @ops_ids
+ * @op_ids: (array length=op_ids_size): an array of ID for the arguments (not %0)
+ * @op_ids_size: size of @ops_ids
*
* Builds a new expression which reprenents a condition (or operation).
*
@@ -1079,7 +1079,7 @@ gda_sql_builder_add_cond (GdaSqlBuilder *builder, GdaSqlOperatorType op, GdaSqlB
* then @op is ignored, and the returned ID represents @op_ids[0] (this avoids any problem for example
* when @op is GDA_SQL_OPERATOR_TYPE_AND and there is in fact only one operand).
*
- * Returns: the ID of the new expression, or 0 if there was an error
+ * Returns: the ID of the new expression, or %0 if there was an error
*
* Since: 4.2
*/
@@ -1130,16 +1130,16 @@ typedef struct {
} BuildTarget;
/**
- * gda_sql_builder_select_add_target_id
+ * gda_sql_builder_select_add_target_id:
* @builder: a #GdaSqlBuilder object
* @table_id: the ID of the expression holding a table reference (not %0)
- * @alias: the alias to give to the target, or %NULL
+ * @alias: (allow-none): the alias to give to the target, or %NULL
*
* Adds a new target to a SELECT statement. If there already exists a target representing
* the same table and the same alias (or with the same absence of alias) then the same target
* ID is returned instead of the ID of a new target.
*
- * Returns: the ID of the new (or existing) target, or 0 if there was an error
+ * Returns: the ID of the new (or existing) target, or %0 if there was an error
*
* Since: 4.2
*/
@@ -1215,14 +1215,14 @@ gda_sql_builder_select_add_target_id (GdaSqlBuilder *builder, GdaSqlBuilderId ta
/**
- * gda_sql_builder_select_add_target
+ * gda_sql_builder_select_add_target:
* @builder: a #GdaSqlBuilder object
* @table_name: the name of the target table
- * @alias: the alias to give to the target, or %NULL
+ * @alias: (allow-none): the alias to give to the target, or %NULL
*
* Adds a new target to a SELECT statement
*
- * Returns: the ID of the new target, or 0 if there was an error
+ * Returns: the ID of the new target, or %0 if there was an error
*
* Since: 4.2
*/
@@ -1251,7 +1251,7 @@ typedef struct {
} BuilderJoin;
/**
- * gda_sql_builder_select_join_targets
+ * gda_sql_builder_select_join_targets:
* @builder: a #GdaSqlBuilder object
* @left_target_id: the ID of the left target to use (not %0)
* @right_target_id: the ID of the right target to use (not %0)
@@ -1265,7 +1265,7 @@ typedef struct {
* %GDA_SQL_SELECT_JOIN_LEFT to %GDA_SQL_SELECT_JOIN_RIGHT or from %GDA_SQL_SELECT_JOIN_RIGHT to
* %GDA_SQL_SELECT_JOIN_LEFT.
*
- * Returns: the ID of the new join, or 0 if there was an error
+ * Returns: the ID of the new join, or %0 if there was an error
*
* Since: 4.2
*/
@@ -1350,7 +1350,7 @@ gda_sql_builder_select_join_targets (GdaSqlBuilder *builder,
}
/**
- * gda_sql_builder_join_add_field
+ * gda_sql_builder_join_add_field:
* @builder: a #GdaSqlBuilder object
* @join_id: the ID of the join to modify (not %0)
* @field_name: the name of the field to use in the join condition (not %NULL)
@@ -1358,7 +1358,7 @@ gda_sql_builder_select_join_targets (GdaSqlBuilder *builder,
* Alter a joins in a SELECT statement to make its condition on the field which name
* is @field_name
*
- * Returns: the ID of the new join, or 0 if there was an error
+ * Returns: the ID of the new join, or %0 if there was an error
*
* Since: 4.2
*/
@@ -1399,11 +1399,11 @@ gda_sql_builder_join_add_field (GdaSqlBuilder *builder, GdaSqlBuilderId join_id,
}
/**
- * gda_sql_builder_select_order_by
+ * gda_sql_builder_select_order_by:
* @builder: a #GdaSqlBuiler
* @expr_id: the ID of the expression to use during sorting (not %0)
* @asc: %TRUE for an ascending sorting
- * @collation_name: name of the collation to use when sorting, or %NULL
+ * @collation_name: (allow-none): name of the collation to use when sorting, or %NULL
*
* Adds a new ORDER BY expression to a SELECT statement.
*
@@ -1439,7 +1439,7 @@ gda_sql_builder_select_order_by (GdaSqlBuilder *builder, GdaSqlBuilderId expr_id
}
/**
- * gda_sql_builder_select_set_distinct
+ * gda_sql_builder_select_set_distinct:
* @builder: a #GdaSqlBuilder object
* @distinct: set to %TRUE to have the DISTINCT requirement
* @expr_id: the ID of the DISTINCT ON expression, or %0 if no expression is to be used. It is ignored
@@ -1485,7 +1485,7 @@ gda_sql_builder_select_set_distinct (GdaSqlBuilder *builder, gboolean distinct,
}
/**
- * gda_sql_builder_select_set_limit
+ * gda_sql_builder_select_set_limit:
* @builder: a #GdaSqlBuilder object
* @limit_count_expr_id: the ID of the LIMIT expression, or %0
* @limit_offset_expr_id: the ID of the OFFSET expression, or %0
@@ -1542,7 +1542,7 @@ gda_sql_builder_select_set_limit (GdaSqlBuilder *builder,
}
/**
- * gda_sql_builder_select_set_having
+ * gda_sql_builder_select_set_having:
* @builder: a #GdaSqlBuilder object
* @cond_id: the ID of the expression to set as HAVING condition, or 0 to unset any previous HAVING condition
*
@@ -1578,7 +1578,7 @@ gda_sql_builder_select_set_having (GdaSqlBuilder *builder, GdaSqlBuilderId cond_
}
/**
- * gda_sql_builder_select_group_by
+ * gda_sql_builder_select_group_by:
* @builder: a #GdaSqlBuilder object
* @expr_id: the ID of the expression to set use in the GROUP BY clause, or 0 to unset any previous GROUP BY clause
*
@@ -1619,14 +1619,14 @@ gda_sql_builder_select_group_by (GdaSqlBuilder *builder, GdaSqlBuilderId expr_id
}
/**
- * gda_sql_builder_add_function
+ * gda_sql_builder_add_function:
* @builder: a #GdaSqlBuilder object
* @function_id: the ID of the functions's name
* @...: a list, terminated with %0, of each function's argument's ID
*
* Builds a new expression which reprenents a function applied to some arguments
*
- * Returns: the ID of the new expression, or 0 if there was an error
+ * Returns: the ID of the new expression, or %0 if there was an error
*
* Since: 4.2
*/
@@ -1664,15 +1664,15 @@ gda_sql_builder_add_function (GdaSqlBuilder *builder, const gchar *func_name, ..
}
/**
- * gda_sql_builder_add_function_v
+ * gda_sql_builder_add_function_v:
* @builder: a #GdaSqlBuilder object
* @function_id: the ID of the functions's name
- * @args: an array of IDs representing the function's arguments
+ * @args: (array length=args_size): an array of IDs representing the function's arguments
* @args_size: @args's size
*
* Builds a new expression which represents a function applied to some arguments
*
- * Returns: the ID of the new expression, or 0 if there was an error
+ * Returns: the ID of the new expression, or %0 if there was an error
*
* Since: 4.2
*/
@@ -1707,14 +1707,14 @@ gda_sql_builder_add_function_v (GdaSqlBuilder *builder, const gchar *func_name,
}
/**
- * gda_sql_builder_add_sub_select
+ * gda_sql_builder_add_sub_select:
* @builder: a #GdaSqlBuilder object
* @sqlst: a pointer to a #GdaSqlStatement, which has to be a SELECT or compound SELECT. This will be copied.
* @steal: if %TRUE, then @sqlst will be "stolen" by @b and should not be used anymore
*
* Adds an expression which is a subselect.
*
- * Returns: the ID of the new expression, or 0 if there was an error
+ * Returns: the ID of the new expression, or %0 if there was an error
*
* Since: 4.2
*/
@@ -1747,7 +1747,7 @@ gda_sql_builder_add_sub_select (GdaSqlBuilder *builder, GdaSqlStatement *sqlst)
}
/**
- * gda_sql_builder_compound_set_type
+ * gda_sql_builder_compound_set_type:
* @builder: a #GdaSqlBuilder object
* @compound_type: a type of compound
*
@@ -1771,7 +1771,7 @@ gda_sql_builder_compound_set_type (GdaSqlBuilder *builder, GdaSqlStatementCompou
}
/**
- * gda_sql_builder_compound_add_sub_select
+ * gda_sql_builder_compound_add_sub_select:
* @builder: a #GdaSqlBuilder object
* @sqlst: a pointer to a #GdaSqlStatement, which has to be a SELECT or compound SELECT. This will be copied.
*
@@ -1802,7 +1802,7 @@ gda_sql_builder_compound_add_sub_select (GdaSqlBuilder *builder, GdaSqlStatement
}
/**
- * gda_sql_builder_add_case
+ * gda_sql_builder_add_case:
* @builder: a #GdaSqlBuilder object
* @test_expr: the expression ID representing the test of the CASE, or %0
* @else_expr: the expression ID representing the ELSE expression, or %0
@@ -1811,7 +1811,7 @@ gda_sql_builder_compound_add_sub_select (GdaSqlBuilder *builder, GdaSqlStatement
*
* Creates a new CASE ... WHEN ... THEN ... ELSE ... END expression.
*
- * Returns: the ID of the new expression, or 0 if there was an error
+ * Returns: the ID of the new expression, or %0 if there was an error
*
* Since: 4.2
*/
@@ -1866,19 +1866,19 @@ gda_sql_builder_add_case (GdaSqlBuilder *builder,
}
/**
- * gda_sql_builder_add_case_v
+ * gda_sql_builder_add_case_v:
* @builder: a #GdaSqlBuilder object
* @test_expr: the expression ID representing the test of the CASE, or %0
* @else_expr: the expression ID representing the ELSE expression, or %0
- * @when_array: an array containing each WHEN expression ID, having at least @args_size elements
- * @then_array: an array containing each THEN expression ID, having at least @args_size elements
+ * @when_array: (array length=args_size): an array containing each WHEN expression ID, having at least @args_size elements
+ * @then_array: (array length=args_size): an array containing each THEN expression ID, having at least @args_size elements
* @args_size: the size of @when_array and @then_array
*
* Creates a new CASE ... WHEN ... THEN ... ELSE ... END expression. The WHEN expression and the THEN
* expression IDs are taken from the @when_array and @then_array at the same index, for each index inferior to
* @args_size.
*
- * Returns: the ID of the new expression, or 0 if there was an error
+ * Returns: the ID of the new expression, or %0 if there was an error
*
* Since: 4.2
*/
@@ -1927,7 +1927,7 @@ gda_sql_builder_add_case_v (GdaSqlBuilder *builder,
}
/**
- * gda_sql_builder_export_expression
+ * gda_sql_builder_export_expression:
* @builder: a #GdaSqlBuilder object
* @id: the ID of the expression to be exported, (must be a valid ID in @builder, not %0)
*
@@ -1954,13 +1954,13 @@ gda_sql_builder_export_expression (GdaSqlBuilder *builder, GdaSqlBuilderId id)
}
/**
- * gda_sql_builder_import_expression
+ * gda_sql_builder_import_expression:
* @builder: a #GdaSqlBuilder object
* @expr: a #GdaSqlExpr obtained using gda_sql_builder_export_expression()
*
* Imports the @expr into @builder.
*
- * Returns: the ID of the new expression, or 0 if there was an error
+ * Returns: the ID of the new expression, or %0 if there was an error
*
* Since: 4.2
*/
diff --git a/libgda/gda-transaction-status.c b/libgda/gda-transaction-status.c
index 01c9732..ad74c10 100644
--- a/libgda/gda-transaction-status.c
+++ b/libgda/gda-transaction-status.c
@@ -1,5 +1,5 @@
/* GDA client library
- * Copyright (C) 1998 - 2006 The GNOME Foundation.
+ * Copyright (C) 1998 - 2010 The GNOME Foundation.
*
* AUTHORS:
* Michael Lausch <michael lausch at>
@@ -130,13 +130,13 @@ gda_transaction_status_get_type (void)
}
/**
- * gda_transaction_status_new
+ * gda_transaction_status_new:
* @name: name for the transaction
*
* Creates a new #GdaTransactionStatus object, which allows a fine-tune and
* full control of transactions to be used with providers.
*
- * Returns: the newly created object.
+ * Returns: (transfer full): the newly created object.
*/
GdaTransactionStatus *
gda_transaction_status_new (const gchar *name)
diff --git a/libgda/gda-tree-manager.c b/libgda/gda-tree-manager.c
index f10c32c..317e9b5 100644
--- a/libgda/gda-tree-manager.c
+++ b/libgda/gda-tree-manager.c
@@ -1,5 +1,5 @@
/* GDA library
- * Copyright (C) 2009 The GNOME Foundation.
+ * Copyright (C) 2009 - 2010 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -157,7 +157,7 @@ GQuark gda_tree_manager_error_quark (void)
}
/**
- * gda_tree_manager_get_type
+ * gda_tree_manager_get_type:
*
* Registers the #GdaTreeManager class on the GLib type system.
*
@@ -301,15 +301,14 @@ _gda_tree_manager_update_children (GdaTreeManager *manager, GdaTreeNode *node, c
/**
- * gda_tree_manager_new_with_func
+ * gda_tree_manager_new_with_func:
* @update_func: the function to call when the manager object is requested to create or update its list of
* #GdaTreeNode nodes
*
* Use this method to create a new #GdaTreeManager if it's more convenient than subclassing; all is needed
- * is the @update_func function which is responsible for creating or updating the children nodes of a specified
- * #GdaTreeNode.
+ * is the @update_func function which is responsible for creating or updating the children nodes of a specified #GdaTreeNode.
*
- * Returns: a new #GdaTreeManager
+ * Returns: (transfer full): a new #GdaTreeManager
*
* Since: 4.2
*/
@@ -322,10 +321,10 @@ gda_tree_manager_new_with_func (GdaTreeManagerNodesFunc update_func)
}
/**
- * gda_tree_manager_add_new_node_attribute
+ * gda_tree_manager_add_new_node_attribute:
* @manager: a #GdaTreeManager
* @attribute: an attribute name
- * @value: the attribute's value, or %NULL
+ * @value: (allow-none): the attribute's value, or %NULL
*
* Requests that for any new node managed (eg. created) by @manager, a new attribute will be set. This allows
* one to customize the attributes of new nodes created by an existing #GdaTreeManager.
@@ -363,10 +362,10 @@ gda_tree_manager_add_new_node_attribute (GdaTreeManager *manager, const gchar *a
}
/**
- * gda_tree_manager_create_node
+ * gda_tree_manager_create_node:
* @manager: a #GdaTreeManager
- * @parent: the parent the new node may have, or %NULL
- * @name: name given to the new node, or %NULL
+ * @parent: (allow-none): the parent the new node may have, or %NULL
+ * @name: (allow-none): name given to the new node, or %NULL
*
* Requests that @manager creates a new #GdaTreeNode. The new node is not in any
* way linked to @manager yet, consider this method as a #GdaTreeNode factory.
@@ -374,7 +373,7 @@ gda_tree_manager_add_new_node_attribute (GdaTreeManager *manager, const gchar *a
* This method is usually used when implementing a #GdaTreeManagerNodesFunc function (to create nodes),
* or when subclassing the #GdaTreeManager.
*
- * Returns: a new #GdaTreeNode
+ * Returns: (transfer full): a new #GdaTreeNode
*
* Since: 4.2
*/
@@ -398,7 +397,7 @@ gda_tree_manager_create_node (GdaTreeManager *manager, GdaTreeNode *parent, cons
}
/**
- * gda_tree_manager_add_manager
+ * gda_tree_manager_add_manager:
* @manager: a #GdaTreeManager object
* @sub: a #GdaTreeManager object to add
*
@@ -420,12 +419,12 @@ gda_tree_manager_add_manager (GdaTreeManager *manager, GdaTreeManager *sub)
}
/**
- * gda_tree_manager_get_managers
+ * gda_tree_manager_get_managers:
* @manager: a #GdaTreeManager object
*
* Get the list of sub managers which have already been added using gda_tree_manager_add_manager()
*
- * Returns: a listof #GdaTreeMenager which should not be modified.
+ * Returns: (transfer none): a list of #GdaTreeMenager which should not be modified.
*
* Since: 4.2
*/
@@ -437,9 +436,9 @@ gda_tree_manager_get_managers (GdaTreeManager *manager)
}
/**
- * gda_tree_manager_set_node_create_func
+ * gda_tree_manager_set_node_create_func:
* @manager: a #GdaTreeManager tree manager object
- * @func: a #GdaTreeManagerNodeFunc function pointer, or %NULL
+ * @func: (allow-none): a #GdaTreeManagerNodeFunc function pointer, or %NULL
*
* Sets the function to be called when a new node is being created by @manager. If @func is %NULL
* then each created node will be a #GdaTreeNode object.
@@ -457,12 +456,12 @@ gda_tree_manager_set_node_create_func (GdaTreeManager *manager, GdaTreeManagerNo
}
/**
- * gda_tree_manager_get_node_create_func
+ * gda_tree_manager_get_node_create_func:
* @manager: a #GdaTreeManager tree manager object
*
* Get the function used by @manager when creating new #GdaTreeNode nodes
*
- * Returns: the #GdaTreeManagerNodeFunc function, or %NULL if the default function is used
+ * Returns: (transfer none): the #GdaTreeManagerNodeFunc function, or %NULL if the default function is used
*
* Since: 4.2
*/
diff --git a/libgda/gda-tree-mgr-columns.c b/libgda/gda-tree-mgr-columns.c
index 285f3c1..cc6fda3 100644
--- a/libgda/gda-tree-mgr-columns.c
+++ b/libgda/gda-tree-mgr-columns.c
@@ -1,5 +1,5 @@
/* GDA library
- * Copyright (C) 2009 The GNOME Foundation.
+ * Copyright (C) 2009 - 2010 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -140,7 +140,7 @@ gda_tree_mgr_columns_dispose (GObject *object)
}
/**
- * gda_tree_mgr_columns_get_type
+ * gda_tree_mgr_columns_get_type:
*
* Returns: the GType
*
@@ -224,7 +224,7 @@ gda_tree_mgr_columns_get_property (GObject *object,
}
/**
- * gda_tree_mgr_columns_new
+ * gda_tree_mgr_columns_new:
* @cnc: a #GdaConnection object
* @schema: a schema name
* @table_name: the name of the table
@@ -232,7 +232,7 @@ gda_tree_mgr_columns_get_property (GObject *object,
* Creates a new #GdaTreeManager object which will add one tree node for each
* column in the table named @table_name in the @schema schema.
*
- * Returns: a new #GdaTreeManager object
+ * Returns: (transfer full): a new #GdaTreeManager object
*
* Since: 4.2
*/
@@ -243,8 +243,8 @@ gda_tree_mgr_columns_new (GdaConnection *cnc, const gchar *schema, const gchar *
g_return_val_if_fail (GDA_IS_CONNECTION (cnc), NULL);
mgr = (GdaTreeMgrColumns*) g_object_new (GDA_TYPE_TREE_MGR_COLUMNS,
- "connection", cnc,
- "schema", schema,
+ "connection", cnc,
+ "schema", schema,
"table-name", table_name, NULL);
return (GdaTreeManager*) mgr;
}
diff --git a/libgda/gda-tree-mgr-label.c b/libgda/gda-tree-mgr-label.c
index 97d4131..f720135 100644
--- a/libgda/gda-tree-mgr-label.c
+++ b/libgda/gda-tree-mgr-label.c
@@ -1,5 +1,5 @@
/* GDA library
- * Copyright (C) 2009 The GNOME Foundation.
+ * Copyright (C) 2009 - 2010 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -105,7 +105,7 @@ gda_tree_mgr_label_dispose (GObject *object)
}
/**
- * gda_tree_mgr_label_get_type
+ * gda_tree_mgr_label_get_type:
*
* Since: 4.2
*/
@@ -173,12 +173,12 @@ gda_tree_mgr_label_get_property (GObject *object,
}
/**
- * gda_tree_mgr_label_new
+ * gda_tree_mgr_label_new:
* @label: a label string
*
* Creates a new #GdaTreeManager object which will add one tree node labelled @label
*
- * Returns: a new #GdaTreeManager object
+ * Returns: (transfer full): a new #GdaTreeManager object
*
* Since: 4.2
*/
diff --git a/libgda/gda-tree-mgr-schemas.c b/libgda/gda-tree-mgr-schemas.c
index 0c1000c..674ba6b 100644
--- a/libgda/gda-tree-mgr-schemas.c
+++ b/libgda/gda-tree-mgr-schemas.c
@@ -1,5 +1,5 @@
/* GDA library
- * Copyright (C) 2009 The GNOME Foundation.
+ * Copyright (C) 2009 - 2010 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -109,7 +109,7 @@ gda_tree_mgr_schemas_dispose (GObject *object)
}
/**
- * gda_tree_mgr_schemas_get_type
+ * gda_tree_mgr_schemas_get_type:
*
* Returns: the GType
*
@@ -181,13 +181,13 @@ gda_tree_mgr_schemas_get_property (GObject *object,
}
/**
- * gda_tree_mgr_schemas_new
+ * gda_tree_mgr_schemas_new:
* @cnc: a #GdaConnection object
*
* Creates a new #GdaTreeManager object which will add one tree node for each database schema found
* in @cnc.
*
- * Returns: a new #GdaTreeManager object
+ * Returns: (transfer full): a new #GdaTreeManager object
*
* Since: 4.2
*/
diff --git a/libgda/gda-tree-mgr-select.c b/libgda/gda-tree-mgr-select.c
index 72e30df..d38dabc 100644
--- a/libgda/gda-tree-mgr-select.c
+++ b/libgda/gda-tree-mgr-select.c
@@ -1,5 +1,5 @@
/* GDA library
- * Copyright (C) 2009 The GNOME Foundation.
+ * Copyright (C) 2009 - 2010 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -129,7 +129,7 @@ gda_tree_mgr_select_dispose (GObject *object)
}
/**
- * gda_tree_mgr_select_get_type
+ * gda_tree_mgr_select_get_type:
*
* Returns: the GType
*
@@ -255,7 +255,7 @@ gda_tree_mgr_select_get_property (GObject *object,
}
/**
- * gda_tree_mgr_select_new
+ * gda_tree_mgr_select_new:
* @cnc: a #GdaConnection object
* @stmt: a #GdaStatement object representing a SELECT statement
* @params: a #GdaSet object representing fixed parameters which are to be used when executing @stmt
@@ -263,7 +263,7 @@ gda_tree_mgr_select_get_property (GObject *object,
* Creates a new #GdaTreeMgrSelect object which will add one tree node for each row in
* the #GdaDataModel resulting from the execution of @stmt.
*
- * Returns: a new #GdaTreeManager object
+ * Returns: (transfer full): a new #GdaTreeManager object
*
* Since: 4.2
*/
diff --git a/libgda/gda-tree-mgr-tables.c b/libgda/gda-tree-mgr-tables.c
index b4ac618..58fddec 100644
--- a/libgda/gda-tree-mgr-tables.c
+++ b/libgda/gda-tree-mgr-tables.c
@@ -1,5 +1,5 @@
/* GDA library
- * Copyright (C) 2009 The GNOME Foundation.
+ * Copyright (C) 2009 - 2010 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -132,7 +132,7 @@ gda_tree_mgr_tables_dispose (GObject *object)
}
/**
- * gda_tree_mgr_select_get_type
+ * gda_tree_mgr_select_get_type:
*
* Returns: the GType
*
@@ -210,14 +210,14 @@ gda_tree_mgr_tables_get_property (GObject *object,
}
/**
- * gda_tree_mgr_tables_new
+ * gda_tree_mgr_tables_new:
* @cnc: a #GdaConnection object
- * @schema: a schema name or %NULL
+ * @schema: (allow-none): a schema name or %NULL
*
* Creates a new #GdaTreeManager object which will add one tree node for each table found in the
* @schema if it is not %NULL, or for each table visible by default in @cnc.
*
- * Returns: a new #GdaTreeManager object
+ * Returns: (transfer full): a new #GdaTreeManager object
*
* Since: 4.2
*/
diff --git a/libgda/gda-tree-node.c b/libgda/gda-tree-node.c
index 2265ed7..47f7a1f 100644
--- a/libgda/gda-tree-node.c
+++ b/libgda/gda-tree-node.c
@@ -1,5 +1,5 @@
/* GDA library
- * Copyright (C) 2009 The GNOME Foundation.
+ * Copyright (C) 2009 - 2010 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -300,7 +300,7 @@ GQuark gda_tree_node_error_quark (void)
}
/**
- * gda_tree_node_get_type
+ * gda_tree_node_get_type:
*
* Registers the #GdaTreeNode class on the GLib type system.
*
@@ -452,12 +452,12 @@ gda_tree_node_dump_children (GdaTreeNode *node, const gchar *prefix, GString *in
}
/**
- * gda_tree_node_new
+ * gda_tree_node_new:
* @name: a name, or %NULL
*
* Creates a new #GdaTreeNode object
*
- * Returns: a new #GdaTreeNode
+ * Returns: (transfer full): a new #GdaTreeNode
*
* Since: 4.2
*/
@@ -467,8 +467,8 @@ gda_tree_node_new (const gchar *name)
return (GdaTreeNode*) g_object_new (GDA_TYPE_TREE_NODE, "name", name, NULL);
}
-/**
- * _gda_tree_node_add_children
+/*
+ * _gda_tree_node_add_children:
* @node: a #GdaTreeNode
* @mgr: a #GdaTreeManager object
* @childen: a list of #GdaTreeNode objects, or %NULL
@@ -605,8 +605,8 @@ _gda_tree_node_add_children (GdaTreeNode *node, GdaTreeManager *mgr, const GSLis
}
}
-/**
- * _gda_tree_node_get_children_for_manager
+/*
+ * _gda_tree_node_get_children_for_manager:
* @node: a #GdaTreeNode
* @manager: a #GdaTreeManager
*
@@ -629,8 +629,8 @@ _gda_tree_node_get_children_for_manager (GdaTreeNode *node, GdaTreeManager *mgr)
return NULL;
}
-/**
- * _gda_tree_node_get_managers_for_children
+/*
+ * _gda_tree_node_get_managers_for_children:
*/
GSList *
_gda_tree_node_get_managers_for_children (GdaTreeNode *node)
@@ -644,8 +644,8 @@ _gda_tree_node_get_managers_for_children (GdaTreeNode *node)
return g_slist_reverse (mgrlist);
}
-/**
- * _gda_tree_node_get_manager_for_child
+/*
+ * _gda_tree_node_get_manager_for_child:
*/
GdaTreeManager *
_gda_tree_node_get_manager_for_child (GdaTreeNode *node, GdaTreeNode *child)
@@ -663,7 +663,7 @@ _gda_tree_node_get_manager_for_child (GdaTreeNode *node, GdaTreeNode *child)
}
/**
- * gda_tree_node_fetch_attribute
+ * gda_tree_node_fetch_attribute:
* @node: a #GdaTreeNode
* @attribute: attribute name as a string
*
@@ -673,7 +673,7 @@ _gda_tree_node_get_manager_for_child (GdaTreeNode *node, GdaTreeNode *child)
* Attributes can have any name, but Libgda proposes some default names,
* see <link linkend="libgda-40-Attributes-manager.synopsis">this section</link>.
*
- * Returns: a read-only #GValue, or %NULL if not attribute named @attribute has been set for @node
+ * Returns: (transfer none): a read-only #GValue, or %NULL if not attribute named @attribute has been set for @node
*
* Since: 4.2
*/
@@ -690,7 +690,7 @@ gda_tree_node_fetch_attribute (GdaTreeNode *node, const gchar *attribute)
}
/**
- * gda_tree_node_get_node_attribute
+ * gda_tree_node_get_node_attribute:
* @node: a #GdaTreeNode
* @attribute: attribute name as a string
*
@@ -701,7 +701,7 @@ gda_tree_node_fetch_attribute (GdaTreeNode *node, const gchar *attribute)
* Attributes can have any name, but Libgda proposes some default names,
* see <link linkend="libgda-40-Attributes-manager.synopsis">this section</link>.
*
- * Returns: a read-only #GValue, or %NULL if not attribute named @attribute has been set for @node
+ * Returns: (transfer none): a read-only #GValue, or %NULL if not attribute named @attribute has been set for @node
*
* Since: 4.2
*/
@@ -714,7 +714,7 @@ gda_tree_node_get_node_attribute (GdaTreeNode *node, const gchar *attribute)
}
/**
- * gda_tree_node_set_node_attribute
+ * gda_tree_node_set_node_attribute:
* @node: a #GdaTreeNode
* @attribute: attribute name
* @value: a #GValue, or %NULL
@@ -755,13 +755,13 @@ gda_tree_node_set_node_attribute (GdaTreeNode *node, const gchar *attribute, con
}
/**
- * gda_tree_node_get_parent
+ * gda_tree_node_get_parent:
* @node: a #GdaTreeNode object
*
* Get the #GdaTreeNode parent of @node in the #GdaTree node belongs to. If @node is at the top level,
* then this method return %NULL.
*
- * Returns: the parent #GdaTreeNode
+ * Returns: (transfer none): the parent #GdaTreeNode
*
* Since: 4.2
*/
@@ -779,12 +779,12 @@ gda_tree_node_get_parent (GdaTreeNode *node)
}
/**
- * gda_tree_node_get_children
+ * gda_tree_node_get_children:
* @node: a #GdaTreeNode object
*
* Get a list of all @node's children, free it with g_slist_free() after usage
*
- * Returns: a new #GSList of #GdaTreeNode objects, or %NULL if @node does not have any child
+ * Returns: (transfer container) (element-type GdaTreeNode): a new #GSList of #GdaTreeNode objects, or %NULL if @node does not have any child
*
* Since: 4.2
*/
@@ -806,13 +806,13 @@ gda_tree_node_get_children (GdaTreeNode *node)
}
/**
- * gda_tree_node_get_child_index
+ * gda_tree_node_get_child_index:
* @node: a #GdaTreeNode object
* @index: a index
*
* Get the #GdaTreeNode child of @node at position @index (starting at 0).
*
- * Returns: the #GdaTreeNode, or %NULL if not found
+ * Returns: (transfer none): the #GdaTreeNode, or %NULL if not found
*
* Since: 4.2
*/
@@ -838,13 +838,13 @@ gda_tree_node_get_child_index (GdaTreeNode *node, gint index)
}
/**
- * gda_tree_node_get_child_name
+ * gda_tree_node_get_child_name:
* @node: a #GdaTreeNode object
* @name: requested node's name
*
* Get the #GdaTreeNode child of @node which has the #GDA_ATTRIBUTE_NAME set to @name
*
- * Returns: the #GdaTreeNode, or %NULL if not found
+ * Returns: (transfer none): the #GdaTreeNode, or %NULL if not found
*
* Since: 4.2
*/
diff --git a/libgda/gda-tree.c b/libgda/gda-tree.c
index cdea51b..3ca4ff6 100644
--- a/libgda/gda-tree.c
+++ b/libgda/gda-tree.c
@@ -1,5 +1,5 @@
/* GDA library
- * Copyright (C) 2009 The GNOME Foundation.
+ * Copyright (C) 2009 - 2010 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -223,7 +223,7 @@ GQuark gda_tree_error_quark (void)
}
/**
- * gda_tree_get_type
+ * gda_tree_get_type:
*
* Registers the #GdaTree class on the GLib type system.
*
@@ -301,11 +301,11 @@ gda_tree_get_property (GObject *object,
}
/**
- * gda_tree_new
+ * gda_tree_new:
*
* Creates a new #GdaTree object
*
- * Returns: a new #GdaTree object
+ * Returns: (transfer full): a new #GdaTree object
*
* Since: 4.2
*/
@@ -317,7 +317,7 @@ gda_tree_new (void)
/**
- * gda_tree_add_manager
+ * gda_tree_add_manager:
* @tree: a #GdaTree object
* @manager: a #GdaTreeManager object
*
@@ -351,7 +351,7 @@ dump_root_attributes (GdaTreeNode *root)
#endif
/**
- * gda_tree_clean
+ * gda_tree_clean:
* @tree: a #GdaTree object
*
* Removes any node in @tree
@@ -375,9 +375,9 @@ gda_tree_clean (GdaTree *tree)
}
/**
- * gda_tree_update_all
+ * gda_tree_update_all:
* @tree: a #GdaTree object
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* Requests that @tree be populated with nodes. If an error occurs, then @tree's contents is left
* unchanged, and otherwise @tree's previous contents is completely replaced by the new one.
@@ -394,10 +394,10 @@ gda_tree_update_all (GdaTree *tree, GError **error)
}
/**
- * gda_tree_update_part
+ * gda_tree_update_part:
* @tree: a #GdaTree object
* @node: a #GdaTreeNode node in @tree
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* Requests that @tree be populated with nodes, starting from @node
*
@@ -425,7 +425,7 @@ gda_tree_update_part (GdaTree *tree, GdaTreeNode *node, GError **error)
}
/**
- * gda_tree_dump
+ * gda_tree_dump:
* @tree: a #GdaTree
* @node: a #GdaTreeNode to start the dump from, or %NULL for a full dump
* @stream: a stream to send the dump to, or %NULL for STDOUT
@@ -457,7 +457,7 @@ static GSList *real_gda_tree_get_nodes_in_path (GdaTree *tree, GSList *segments,
static GSList *decompose_path_as_segments (const gchar *path, gboolean use_names);
/**
- * gda_tree_get_nodes_in_path
+ * gda_tree_get_nodes_in_path:
* @tree: a #GdaTree object
* @tree_path: full path to the required nodes (if @use_names is %TRUE, then it must start with '/')
* @use_names: if %TRUE, then @tree_path will be interpreted as a unix style path, and if %FALSE,
@@ -468,7 +468,7 @@ static GSList *decompose_path_as_segments (const gchar *path, gboolean use_names
*
* As a corner case if @tree_path is %NULL, then the returned list contains all the top level nodes.
*
- * Returns: a new list of #GdaTreeNode pointers, free it with g_slist_free()
+ * Returns: (transfer container) (element-type GdaTreeNode): a new list of #GdaTreeNode pointers, free it with g_slist_free()
*
* Since: 4.2
*/
@@ -575,13 +575,13 @@ real_gda_tree_get_nodes_in_path (GdaTree *tree, GSList *segments, gboolean use_n
static gboolean build_node_path (GdaTree *tree, GdaTreeNode *node, GArray *array);
/**
- * gda_tree_get_node_path
+ * gda_tree_get_node_path:
* @tree: a #GdaTree
* @node: a #GdaTreeNode node in @tree
*
* Get the path associated to @node in @tree.
*
- * Returns: a new string, or %NULL if @node is not in @tree
+ * Returns: (transfer full): a new string, or %NULL if @node is not in @tree
*
* Since: 4.2
*/
@@ -644,7 +644,7 @@ build_node_path (GdaTree *tree, GdaTreeNode *node, GArray *array)
*
* Locates a #GdaTreeNode using the @tree_path path.
*
- * Returns: the requested #GdaTreeNode pointer, or %NULL if not found
+ * Returns: (transfer none): the requested #GdaTreeNode pointer, or %NULL if not found
*
* Since: 4.2
*/
@@ -671,13 +671,13 @@ gda_tree_get_node (GdaTree *tree, const gchar *tree_path, gboolean use_names)
}
/**
- * gda_tree_get_node_manager
+ * gda_tree_get_node_manager:
* @tree: a #GdaTree
* @node: a #GdaTreeNode present in @tree
*
* Get the #GdaTreeManager which created @node in @tree
*
- * Returns: the #GdaTreeManager, or %NULL if @node is not present in @tree
+ * Returns: (transfer none): the #GdaTreeManager, or %NULL if @node is not present in @tree
*
* Since: 4.2
*/
@@ -851,7 +851,7 @@ split_indexed_path (const gchar *path, gboolean *out_error)
}
/**
- * gda_tree_set_attribute
+ * gda_tree_set_attribute:
* @tree: a #GdaTree object
* @attribute: attribute name
* @value: a #GValue, or %NULL
diff --git a/libgda/gda-value.c b/libgda/gda-value.c
index 13b4c89..c135f22 100644
--- a/libgda/gda-value.c
+++ b/libgda/gda-value.c
@@ -1,5 +1,5 @@
-/* GDA common library
- * Copyright (C) 1998 - 2008 The GNOME Foundation.
+/* GDA library
+ * Copyright (C) 1998 - 2010 The GNOME Foundation.
*
* AUTHORS:
* Michael Lausch <michael lausch at>
@@ -308,13 +308,14 @@ gda_binary_get_type (void)
}
/**
- * gda_binary_copy
+ * gda_binary_copy:
* @boxed: source to get a copy from.
*
* Creates a new #GdaBinary structure from an existing one.
- * Returns: a newly allocated #GdaBinary which contains a copy of
- * information in @boxed.
+ * Returns: (transfer full): a newly allocated #GdaBinary which contains a copy of information in @boxed.
+ *
+ * Free-function: gda_binary_free
*/
gpointer
gda_binary_copy (gpointer boxed)
@@ -332,8 +333,8 @@ gda_binary_copy (gpointer boxed)
}
/**
- * gda_binary_free
- * @boxed: #GdaBinary to free.
+ * gda_binary_free:
+ * @boxed: (transfer full): #GdaBinary to free.
*
* Deallocates all memory associated to the given #GdaBinary.
*/
@@ -405,13 +406,14 @@ gda_blob_get_type (void)
}
/**
- * gda_blob_copy
+ * gda_blob_copy:
* @boxed: source to get a copy from.
*
* Creates a new #GdaBlob structure from an existing one.
- * Returns: a newly allocated #GdaBlob which contains a copy of
- * information in @boxed.
+ * Returns: (transfer full): a newly allocated #GdaBlob which contains a copy of information in @boxed.
+ *
+ * Free-function: gda_blob_free
*/
gpointer
gda_blob_copy (gpointer boxed)
@@ -432,8 +434,8 @@ gda_blob_copy (gpointer boxed)
}
/**
- * gda_blob_free
- * @boxed: #GdaBlob to free.
+ * gda_blob_free:
+ * @boxed: (transfer full): #GdaBlob to free.
*
* Deallocates all memory associated to the given #GdaBlob.
*/
@@ -452,7 +454,7 @@ gda_blob_free (gpointer boxed)
}
/**
- * gda_blob_set_op
+ * gda_blob_set_op:
* @blob: a #GdaBlob value
* @op: a #GdaBlobOp object, or %NULL
*
@@ -738,13 +740,14 @@ gda_numeric_get_type (void)
}
/**
- * gda_numeric_copy
+ * gda_numeric_copy:
* @boxed: source to get a copy from.
*
* Creates a new #GdaNumeric structure from an existing one.
- * Returns: a newly allocated #GdaNumeric which contains a copy of
- * information in @boxed.
+ * Returns: (transfer full): a newly allocated #GdaNumeric which contains a copy of information in @boxed.
+ *
+ * Free-function: gda_numeric_free
*/
gpointer
@@ -764,8 +767,8 @@ gda_numeric_copy (gpointer boxed)
}
/**
- * gda_numeric_free
- * @boxed: a #GdaNumeric pointer
+ * gda_numeric_free:
+ * @boxed: (transfer full): a #GdaNumeric pointer
*
* Deallocates all memory associated to the given @boxed
*/
@@ -949,10 +952,10 @@ gda_time_free (gpointer boxed)
}
/**
- * gda_time_valid
+ * gda_time_valid:
* @time: a #GdaTime value to check if it is valid
*
- * Returns: #TRUE if #GdaTime is valid; FALSE otherwise.
+ * Returns: #TRUE if #GdaTime is valid; %FALSE otherwise.
*
* Since: 4.2
*/
@@ -1084,10 +1087,10 @@ gda_timestamp_free (gpointer boxed)
}
/**
- * gda_timestamp_valid
+ * gda_timestamp_valid:
* @timestamp: a #GdaTimestamp value to check if it is valid
*
- * Returns: #TRUE if #GdaTimestamp is valid; FALSE otherwise.
+ * Returns: #TRUE if #GdaTimestamp is valid; %FALSE otherwise.
*
* Since: 4.2
*/
@@ -1119,13 +1122,14 @@ gda_timestamp_valid (const GdaTimestamp *timestamp)
}
/**
- * gda_value_new
+ * gda_value_new:
* @type: the new value type.
*
* Makes a new #GValue of type @type.
*
- * Returns: the newly created #GValue with the specified @type.
- * You need to set the value in the returned GValue.
+ * Returns: (transfer full): the newly created #GValue with the specified @type. You need to set the value in the returned GValue.
+ *
+ * Free-function: gda_value_free
*/
GValue *
gda_value_new (GType type)
@@ -1139,13 +1143,15 @@ gda_value_new (GType type)
}
/**
- * gda_value_new_binary
+ * gda_value_new_binary:
* @val: value to set for the new #GValue.
* @size: the size of the memory pool pointer to by @val.
*
* Makes a new #GValue of type #GDA_TYPE_BINARY with value @val.
*
- * Returns: the newly created #GValue.
+ * Returns: (transfer full): the newly created #GValue.
+ *
+ * Free-function: gda_value_free
*/
GValue *
gda_value_new_binary (const guchar *val, glong size)
@@ -1166,13 +1172,15 @@ gda_value_new_binary (const guchar *val, glong size)
}
/**
- * gda_value_new_blob
+ * gda_value_new_blob:
* @val: value to set for the new #GValue.
* @size: the size of the memory pool pointer to by @val.
*
* Makes a new #GValue of type #GDA_TYPE_BLOB with the data contained by @val.
*
- * Returns: the newly created #GValue.
+ * Returns: (transfer full): the newly created #GValue.
+ *
+ * Free-function: gda_value_free
*/
GValue *
gda_value_new_blob (const guchar *val, glong size)
@@ -1196,13 +1204,15 @@ gda_value_new_blob (const guchar *val, glong size)
}
/**
- * gda_value_new_blob_from_file
+ * gda_value_new_blob_from_file:
* @filename: name of the file to manipulate
*
* Makes a new #GValue of type #GDA_TYPE_BLOB interfacing with the contents of the file
* named @filename
*
- * Returns: the newly created #GValue.
+ * Returns: (transfer full): the newly created #GValue.
+ *
+ * Free-function: gda_value_free
*/
GValue *
gda_value_new_blob_from_file (const gchar *filename)
@@ -1221,13 +1231,15 @@ gda_value_new_blob_from_file (const gchar *filename)
}
/**
- * gda_value_new_timestamp_from_timet
+ * gda_value_new_timestamp_from_timet:
* @val: value to set for the new #GValue.
*
* Makes a new #GValue of type #GDA_TYPE_TIMESTAMP with value @val
* (of type time_t).
*
- * Returns: the newly created #GValue.
+ * Returns: (transfer full): the newly created #GValue.
+ *
+ * Free-function: gda_value_free
*/
GValue *
gda_value_new_timestamp_from_timet (time_t val)
@@ -1255,7 +1267,7 @@ gda_value_new_timestamp_from_timet (time_t val)
}
/**
- * gda_value_new_from_string
+ * gda_value_new_from_string:
* @as_string: stringified representation of the value.
* @type: the new value type.
*
@@ -1266,8 +1278,9 @@ gda_value_new_timestamp_from_timet (time_t val)
* This function is typically used when reading configuration files or other non-user input that should be locale
* independent.
*
- * Returns: the newly created #GValue or %NULL if the string representation
- * cannot be converted to the specified @type.
+ * Returns: (transfer full): the newly created #GValue or %NULL if the string representation cannot be converted to the specified @type.
+ *
+ * Free-function: gda_value_free
*/
GValue *
gda_value_new_from_string (const gchar *as_string, GType type)
@@ -1286,7 +1299,7 @@ gda_value_new_from_string (const gchar *as_string, GType type)
}
/**
- * gda_value_new_from_xml
+ * gda_value_new_from_xml:
* @node: an XML node representing the value.
*
* Creates a GValue from an XML representation of it. That XML
@@ -1298,7 +1311,9 @@ gda_value_new_from_string (const gchar *as_string, GType type)
* This function is typically used when reading configuration files or other non-user input that should be locale
* independent.
*
- * Returns: the newly created #GValue.
+ * Returns: (transfer full): the newly created #GValue.
+ *
+ * Free-function: gda_value_free
*/
GValue *
gda_value_new_from_xml (const xmlNodePtr node)
@@ -1327,8 +1342,8 @@ gda_value_new_from_xml (const xmlNodePtr node)
}
/**
- * gda_value_free
- * @value: the resource to free.
+ * gda_value_free:
+ * @value: (transfer full): the resource to free.
*
* Deallocates all memory associated to a #GValue.
*/
@@ -1366,13 +1381,12 @@ gda_value_reset_with_type (GValue *value, GType type)
/**
- * gda_value_is_null
+ * gda_value_is_null:
* @value: value to test.
*
* Tests if a given @value is of type #GDA_TYPE_NULL.
*
- * Returns: a boolean that says whether or not @value is of type
- * #GDA_TYPE_NULL.
+ * Returns: a boolean that says whether or not @value is of type #GDA_TYPE_NULL.
*/
gboolean
gda_value_is_null (const GValue *value)
@@ -1382,11 +1396,10 @@ gda_value_is_null (const GValue *value)
}
/**
- * gda_value_is_number
+ * gda_value_is_number:
* @value: a #GValue.
*
- * Gets whether the value stored in the given #GValue is of
- * numeric type or not.
+ * Gets whether the value stored in the given #GValue is of numeric type or not.
*
* Returns: %TRUE if a number, %FALSE otherwise.
*/
@@ -1406,15 +1419,17 @@ gda_value_is_number (const GValue *value)
}
/**
- * gda_value_copy
+ * gda_value_copy:
* @value: value to get a copy from.
*
* Creates a new #GValue from an existing one.
*
- * Returns: a newly allocated #GValue with a copy of the data in @value.
+ * Returns: (transfer full): a newly allocated #GValue with a copy of the data in @value.
+ *
+ * Free-function: gda_value_free
*/
GValue *
-gda_value_copy (const GValue *value)
+gda_value_copy (const GValue *value)
{
GValue *copy;
@@ -1431,10 +1446,10 @@ gda_value_copy (const GValue *value)
}
/**
- * gda_value_get_binary
+ * gda_value_get_binary:
* @value: a #GValue whose value we want to get.
*
- * Returns: the value stored in @value.
+ * Returns: (transfer none): the value stored in @value.
*/
G_CONST_RETURN GdaBinary *
gda_value_get_binary (const GValue *value)
@@ -1451,7 +1466,7 @@ gda_value_get_binary (const GValue *value)
/**
- * gda_value_set_binary
+ * gda_value_set_binary:
* @value: a #GValue that will store @val.
* @binary: a #GdaBinary structure with the data and its size to be stored in @value.
*
@@ -1473,9 +1488,9 @@ gda_value_set_binary (GValue *value, const GdaBinary *binary)
}
/**
- * gda_value_take_binary
+ * gda_value_take_binary:
* @value: a #GValue that will store @val.
- * @binary: a #GdaBinary structure with the data and its size to be stored in @value.
+ * @binary: (transfer full): a #GdaBinary structure with the data and its size to be stored in @value.
*
* Stores @val into @value, but on the contrary to gda_value_set_binary(), the @binary
* argument is not copied, but used as-is and it should be considered owned by @value.
@@ -1492,7 +1507,7 @@ gda_value_take_binary (GValue *value, GdaBinary *binary)
}
/**
- * gda_value_set_blob
+ * gda_value_set_blob:
* @value: a #GValue that will store @val.
* @blob: a #GdaBlob structure with the data and its size to be stored in @value.
*
@@ -1510,10 +1525,10 @@ gda_value_set_blob (GValue *value, const GdaBlob *blob)
}
/**
- * gda_value_get_blob
+ * gda_value_get_blob:
* @value: a #GValue whose value we want to get.
*
- * Returns: the value stored in @value.
+ * Returns: (transfer none): the value stored in @value.
*/
G_CONST_RETURN GdaBlob *
gda_value_get_blob (const GValue *value)
@@ -1529,9 +1544,9 @@ gda_value_get_blob (const GValue *value)
}
/**
- * gda_value_take_blob
+ * gda_value_take_blob:
* @value: a #GValue that will store @val.
- * @blob: a #GdaBlob structure with the data and its size to be stored in @value.
+ * @blob: (transfer full): a #GdaBlob structure with the data and its size to be stored in @value.
*
* Stores @val into @value, but on the contrary to gda_value_set_blob(), the @blob
* argument is not copied, but used as-is and it should be considered owned by @value.
@@ -1548,10 +1563,10 @@ gda_value_take_blob (GValue *value, GdaBlob *blob)
}
/**
- * gda_value_get_geometric_point
+ * gda_value_get_geometric_point:
* @value: a #GValue whose value we want to get.
*
- * Returns: the value stored in @value.
+ * Returns: (transfer none): the value stored in @value.
*/
G_CONST_RETURN GdaGeometricPoint *
gda_value_get_geometric_point (const GValue *value)
@@ -1562,7 +1577,7 @@ gda_value_get_geometric_point (const GValue *value)
}
/**
- * gda_value_set_geometric_point
+ * gda_value_set_geometric_point:
* @value: a #GValue that will store @val.
* @val: value to be stored in @value.
*
@@ -1580,10 +1595,10 @@ gda_value_set_geometric_point (GValue *value, const GdaGeometricPoint *val)
}
/**
- * gda_value_get_list
+ * gda_value_get_list:
* @value: a #GValue whose value we want to get.
*
- * Returns: the value stored in @value.
+ * Returns: (transfer none): the value stored in @value.
*/
G_CONST_RETURN GdaValueList *
gda_value_get_list (const GValue *value)
@@ -1594,7 +1609,7 @@ gda_value_get_list (const GValue *value)
}
/**
- * gda_value_set_list
+ * gda_value_set_list:
* @value: a #GValue that will store @val.
* @val: value to be stored in @value.
*
@@ -1614,7 +1629,7 @@ gda_value_set_list (GValue *value, const GdaValueList *val)
}
/**
- * gda_value_set_null
+ * gda_value_set_null:
* @value: a #GValue that will store a value of type #GDA_TYPE_NULL.
*
* Sets the type of @value to #GDA_TYPE_NULL.
@@ -1631,7 +1646,7 @@ gda_value_set_null (GValue *value)
* gda_value_get_numeric
* @value: a #GValue whose value we want to get.
*
- * Returns: the value stored in @value.
+ * Returns: (transfer none): the value stored in @value.
*/
G_CONST_RETURN GdaNumeric *
gda_value_get_numeric (const GValue *value)
@@ -1642,7 +1657,7 @@ gda_value_get_numeric (const GValue *value)
}
/**
- * gda_value_set_numeric
+ * gda_value_set_numeric:
* @value: a #GValue that will store @val.
* @val: value to be stored in @value.
*
@@ -1660,7 +1675,7 @@ gda_value_set_numeric (GValue *value, const GdaNumeric *val)
}
/**
- * gda_value_get_short
+ * gda_value_get_short:
* @value: a #GValue whose value we want to get.
*
* Returns: the value stored in @value.
@@ -1674,7 +1689,7 @@ gda_value_get_short (const GValue *value)
}
/**
- * gda_value_set_short
+ * gda_value_set_short:
* @value: a #GValue that will store @val.
* @val: value to be stored in @value.
*
@@ -1691,7 +1706,7 @@ gda_value_set_short (GValue *value, gshort val)
}
/**
- * gda_value_get_ushort
+ * gda_value_get_ushort:
* @value: a #GValue whose value we want to get.
*
* Returns: the value stored in @value.
@@ -1705,7 +1720,7 @@ gda_value_get_ushort (const GValue *value)
}
/**
- * gda_value_set_ushort
+ * gda_value_set_ushort:
* @value: a #GValue that will store @val.
* @val: value to be stored in @value.
*
@@ -1723,10 +1738,10 @@ gda_value_set_ushort (GValue *value, gushort val)
/**
- * gda_value_get_time
+ * gda_value_get_time:
* @value: a #GValue whose value we want to get.
*
- * Returns: the value stored in @value.
+ * Returns: (transfer none): the value stored in @value.
*/
const GdaTime *
gda_value_get_time (const GValue *value)
@@ -1737,7 +1752,7 @@ gda_value_get_time (const GValue *value)
}
/**
- * gda_value_set_time
+ * gda_value_set_time:
* @value: a #GValue that will store @val.
* @val: value to be stored in @value.
*
@@ -1755,10 +1770,10 @@ gda_value_set_time (GValue *value, const GdaTime *val)
}
/**
- * gda_value_get_timestamp
+ * gda_value_get_timestamp:
* @value: a #GValue whose value we want to get.
*
- * Returns: the value stored in @value.
+ * Returns: (transfer none): the value stored in @value.
*/
const GdaTimestamp *
gda_value_get_timestamp (const GValue *value)
@@ -1769,7 +1784,7 @@ gda_value_get_timestamp (const GValue *value)
}
/**
- * gda_value_set_timestamp
+ * gda_value_set_timestamp:
* @value: a #GValue that will store @val.
* @val: value to be stored in @value.
*
@@ -1787,7 +1802,7 @@ gda_value_set_timestamp (GValue *value, const GdaTimestamp *val)
}
/**
- * gda_value_set_from_string
+ * gda_value_set_from_string:
* @value: a #GValue that will store @val.
* @as_string: the stringified representation of the value.
* @type: the type of the value
@@ -1825,7 +1840,7 @@ gda_value_set_from_string (GValue *value,
}
/**
- * gda_value_set_from_value
+ * gda_value_set_from_value:
* @value: a #GValue.
* @from: the value to copy from.
*
@@ -1858,7 +1873,7 @@ gda_value_set_from_value (GValue *value, const GValue *from)
}
/**
- * gda_value_stringify
+ * gda_value_stringify:
* @value: a #GValue.
*
* Converts a GValue to its string representation which is a human readable value. Note that the
@@ -1868,8 +1883,7 @@ gda_value_set_from_value (GValue *value, const GValue *from)
*
* Dates are converted in a YYYY-MM-DD format.
*
- * Returns: a new string, or %NULL if the conversion cannot be done. Free the value with a g_free() when you've finished
- * using it.
+ * Returns: (transfer full): a new string, or %NULL if the conversion cannot be done. Free the value with a g_free() when you've finished using it.
*/
gchar *
gda_value_stringify (const GValue *value)
@@ -1932,7 +1946,7 @@ gda_value_stringify (const GValue *value)
}
/**
- * gda_value_differ
+ * gda_value_differ:
* @value1: a #GValue to compare.
* @value2: the other #GValue to be compared to @value1.
*
@@ -2098,7 +2112,7 @@ gda_value_differ (const GValue *value1, const GValue *value2)
}
/**
- * gda_value_compare
+ * gda_value_compare:
* @value1: a #GValue to compare (not %NULL)
* @value2: the other #GValue to be compared to @value1 (not %NULL)
*
@@ -2411,12 +2425,12 @@ to_string (const GValue *value)
/**
- * gda_value_to_xml
+ * gda_value_to_xml:
* @value: a #GValue.
*
* Serializes the given #GValue to an XML node string.
*
- * Returns: the XML node. Once not needed anymore, you should free it.
+ * Returns: (transfer full): the XML node. Once not needed anymore, you should free it.
*/
xmlNodePtr
gda_value_to_xml (const GValue *value)
@@ -2554,9 +2568,9 @@ gda_ushort_get_type (void) {
#define MYMIN(a,b) (((b) > 0) ? ((a) < (b) ? (a) : (b)) : (a))
/**
- * gda_binary_to_string
+ * gda_binary_to_string:
* @bin: a correctly filled @GdaBinary structure
- * @maxlen: a maximum len used to truncate, or 0 for no maximum length
+ * @maxlen: a maximum len used to truncate, or %0 for no maximum length
*
* Converts all the non printable characters of bin->data into the "\xyz" representation
* where "xyz" is the octal representation of the byte, and the '\' (backslash) character
@@ -2569,7 +2583,7 @@ gda_ushort_get_type (void) {
* chunk. Note that this function is internally called when transforming a binary value to
* a string for example when using g_value_transform() or gda_value_stringify().
*
- * Returns: a new string from @bin
+ * Returns: (transfer full): a new string from @bin
*/
gchar *
gda_binary_to_string (const GdaBinary *bin, guint maxlen)
@@ -2637,14 +2651,14 @@ gda_binary_to_string (const GdaBinary *bin, guint maxlen)
}
/**
- * gda_string_to_binary
+ * gda_string_to_binary:
* @str: a string to convert
*
* Performs the reverse of gda_binary_to_string() (note that for any "\xyz" succession
* of 4 characters where "xyz" represents a valid octal value, the resulting read value will
* be modulo 256)
*
- * Returns: a new #GdaBinary if no error were found in @str, or NULL otherwise
+ * Returns: (transfer full): a new #GdaBinary if no error were found in @str, or NULL otherwise
*/
GdaBinary *
gda_string_to_binary (const gchar *str)
@@ -2705,7 +2719,7 @@ gda_string_to_binary (const gchar *str)
}
/**
- * gda_blob_to_string
+ * gda_blob_to_string:
* @blob: a correctly filled @GdaBlob structure
* @maxlen: a maximum len used to truncate, or 0 for no maximum length
*
@@ -2713,7 +2727,7 @@ gda_string_to_binary (const gchar *str)
* where xxx is the octal representation of the byte, and the '\' (backslash) character
* is converted to "\\".
*
- * Returns: a new string from @blob
+ * Returns: (transfer full): a new string from @blob
*/
gchar *
gda_blob_to_string (GdaBlob *blob, guint maxlen)
@@ -2726,12 +2740,12 @@ gda_blob_to_string (GdaBlob *blob, guint maxlen)
}
/**
- * gda_string_to_blob
+ * gda_string_to_blob:
* @str: a string to convert
*
* Performs the reverse of gda_blob_to_string().
*
- * Returns: a new #gdaBlob if no error were found in @str, or NULL otherwise
+ * Returns: (transfer full): a new #gdaBlob if no error were found in @str, or NULL otherwise
*/
GdaBlob *
gda_string_to_blob (const gchar *str)
diff --git a/libgda/gda-xa-transaction.c b/libgda/gda-xa-transaction.c
index df703a9..eee2371 100644
--- a/libgda/gda-xa-transaction.c
+++ b/libgda/gda-xa-transaction.c
@@ -1,5 +1,5 @@
/* GDA library
- * Copyright (C) 2008 The GNOME Foundation.
+ * Copyright (C) 2008 - 2010 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -237,14 +237,14 @@ gda_xa_transaction_get_type (void)
}
/**
- * gda_xa_transaction_new
+ * gda_xa_transaction_new:
* @format: a format ID
* @global_transaction_id: the global transaction ID
*
* Creates a new #GdaXaTransaction object, which will control the process of
* performing a distributed transaction across several connections.
*
- * Returns: the newly created object.
+ * Returns: (transfer full): the newly created object.
*/
GdaXaTransaction *
gda_xa_transaction_new (guint32 format, const gchar *global_transaction_id)
@@ -255,11 +255,11 @@ gda_xa_transaction_new (guint32 format, const gchar *global_transaction_id)
}
/**
- * gda_xa_transaction_register_connection
+ * gda_xa_transaction_register_connection:
* @xa_trans: a #GdaXaTransaction object
* @cnc: the connection to add to @xa_trans
* @branch: the branch qualifier
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* Registers @cnc to be used by @xa_trans to create a distributed transaction.
*
@@ -267,7 +267,7 @@ gda_xa_transaction_new (guint32 format, const gchar *global_transaction_id)
* some connections may not be registered at all with a #GdaXaTransaction object because the database
* provider being used does not support it.
*
- * Returns: TRUE if no error occurred
+ * Returns: %TRUE if no error occurred
*/
gboolean
gda_xa_transaction_register_connection (GdaXaTransaction *xa_trans, GdaConnection *cnc,
@@ -325,7 +325,7 @@ gda_xa_transaction_register_connection (GdaXaTransaction *xa_trans, GdaConnecti
}
/**
- * gda_xa_transaction_unregister_connection
+ * gda_xa_transaction_unregister_connection:
* @xa_trans: a #GdaXaTransaction object
* @cnc: the connection to add to @xa_trans
*
@@ -349,9 +349,9 @@ gda_xa_transaction_unregister_connection (GdaXaTransaction *xa_trans, GdaConnect
}
/**
- * gda_xa_transaction_begin
+ * gda_xa_transaction_begin:
* @xa_trans: a #GdaXaTransaction object
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* Begins a distributed transaction (managed by @xa_trans). Please note that this phase may fail
* for some connections if a (normal) transaction is already started (this depends on the database
@@ -427,10 +427,10 @@ gda_xa_transaction_begin (GdaXaTransaction *xa_trans, GError **error)
}
/**
- * gda_xa_transaction_commit
+ * gda_xa_transaction_commit:
* @xa_trans: a #GdaXaTransaction object
* @cnc_to_recover: a place to store the list of connections for which the commit phase failed, or %NULL
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* Commits a distributed transaction (managed by @xa_trans). The commit is composed of two phases:
* <itemizedlist>
@@ -568,13 +568,13 @@ gda_xa_transaction_commit (GdaXaTransaction *xa_trans, GSList **cnc_to_recover,
}
/**
- * gda_xa_transaction_rollback
+ * gda_xa_transaction_rollback:
* @xa_trans: a #GdaXaTransaction object
- * @error: a place to store errors, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* Cancels a distributed transaction (managed by @xa_trans).
*
- * Returns: TRUE if no error occurred
+ * Returns: %TRUE if no error occurred
*/
gboolean
gda_xa_transaction_rollback (GdaXaTransaction *xa_trans, GError **error)
@@ -607,17 +607,16 @@ gda_xa_transaction_rollback (GdaXaTransaction *xa_trans, GError **error)
}
/**
- * gda_xa_transaction_commit_recovered
+ * gda_xa_transaction_commit_recovered:
* @xa_trans: a #GdaXaTransaction object
- * @cnc_to_recover: a place to store the list of connections for which the there were data to recover and which failed
- * to be actually committed, or %NULL
- * @error: a place to store errors, or %NULL
+ * @cnc_to_recover: (allow-none): a place to store the list of connections for which the there were data to recover and which failed to be actually committed, or %NULL
+ * @error: (allow-none): a place to store errors, or %NULL
*
* Tries to commit the data prepared but which failed to commit (see gda_xa_transaction_commit()). This
* method allows one to terminate a distributed transaction which succeeded but for which some
* connections needed to be recovered.
*
- * Returns: TRUE if all the data which was still uncommitted has been committed
+ * Returns: %TRUE if all the data which was still uncommitted has been committed
*/
gboolean
gda_xa_transaction_commit_recovered (GdaXaTransaction *xa_trans, GSList **cnc_to_recover, GError **error)
@@ -697,14 +696,14 @@ gda_xa_transaction_commit_recovered (GdaXaTransaction *xa_trans, GSList **cnc_to
}
/**
- * gda_xa_transaction_id_to_string
+ * gda_xa_transaction_id_to_string:
* @xid: a #GdaXaTransactionId pointer
*
* Creates a string representation of @xid, in the format <gtrid>,<bqual>,<formatID> the
* <gtrid> and <bqual> strings contain alphanumeric characters, and non alphanumeric characters
* are converted to "%ab" where ab is the hexadecimal representation of the character.
*
- * Returns: a new string representation of @xid
+ * Returns: (transfer full): a new string representation of @xid
*/
gchar *
gda_xa_transaction_id_to_string (const GdaXaTransactionId *xid)
@@ -744,13 +743,15 @@ gda_xa_transaction_id_to_string (const GdaXaTransactionId *xid)
}
/**
- * gda_xa_transaction_string_to_id
+ * gda_xa_transaction_string_to_id:
* @str: a string representation of a #GdaXaTransactionId, in the "gtrid,bqual,formatID" format
*
* Creates a new #GdaXaTransactionId structure from its string representation, it's the opposite
* of gda_xa_transaction_id_to_string().
*
- * Returns: a new #GdaXaTransactionId structure, or %NULL in @str has a wrong format
+ * Returns: (transfer full): a new #GdaXaTransactionId structure, or %NULL in @str has a wrong format
+ *
+ * Free-function: g_free
*/
GdaXaTransactionId *
gda_xa_transaction_string_to_id (const gchar *str)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
