GNOME.org
 

[libgda: 2/4] Introspection: gtk-doc annotation fix

commit 505c0dabb94fe68a2ff320d33b14ae069b95d81b
Author: Pavlo Solntsev <p sun fun gmail com>
Date:   Thu Aug 15 07:39:35 2019 -0500

    Introspection: gtk-doc annotation fix

 libgda/gda-util.c | 49 +++++++++++++++++++++++--------------------------
 1 file changed, 23 insertions(+), 26 deletions(-)
---
diff --git a/libgda/gda-util.c b/libgda/gda-util.c
index 05cc2efb4..12d821a19 100644
--- a/libgda/gda-util.c
+++ b/libgda/gda-util.c
@@ -75,7 +75,7 @@
  * understand and remember name. For Example the G_TYPE_STRING is converted to "string"
  * whereas g_type_name() converts it to "gchararray".
  *
- * Returns: the GDA's string representing the given #GType or the name
+ * Returns: (transfer none) the GDA's string representing the given #GType or the name
  * returned by #g_type_name.
  */
 const gchar *
@@ -197,7 +197,7 @@ gda_g_type_from_string (const gchar *str)
  * Escapes @string to make it understandable by a DBMS. The escape method is very common and replaces any
  * occurrence of "'" with "''" and "\" with "\\"
  *
- * Returns: a new string
+ * Returns: (transfer full) (nullable): a new string
  */
 gchar *
 gda_default_escape_string (const gchar *string)
@@ -251,7 +251,7 @@ gda_default_escape_string (const gchar *string)
  * Do the reverse of gda_default_escape_string(): transforms any "''" into "'", any
  * "\\" into "\" and any "\'" into "'". 
  *
- * Returns: a new unescaped string, or %NULL in an error was found in @string
+ * Returns: (transfer full) (nullable): a new unescaped string, or %NULL in an error was found in @string
  */
 gchar *
 gda_default_unescape_string (const gchar *string)
@@ -308,7 +308,7 @@ gda_default_unescape_string (const gchar *string)
 /**
  * gda_utility_check_data_model_v: (rename-to gda_utility_check_data_model)
  * @model: a #GdaDataModel object
- * @nbcols: the minimum requested number of columns
+ * @nbcols: the minimum requested number of columns. Lenght of @types
  * @types: (array length=nbcols): array with @nbcols length of type GType or null (if any data type is 
accepted)
  *
  * Check the column types of a GdaDataModel.
@@ -569,7 +569,7 @@ gda_utility_data_model_dump_data_to_xml (GdaDataModel *model, xmlNodePtr parent,
  *
  * Finds the description of a field into Metadata from a #GdaDataModel.
  *
- * Returns: The field's description, or NULL if description is not set
+ * Returns: (transfer none) (nullable): The field's description, or NULL if description is not set
  */
 const gchar *
 gda_utility_data_model_find_column_description (GdaDataSelect *model, const gchar *field_name)
@@ -617,7 +617,7 @@ gda_utility_data_model_find_column_description (GdaDataSelect *model, const gcha
  * gda_utility_holder_load_attributes:
  * @holder: a #GdaHolder
  * @node: an xmlNodePtr with a &lt;parameter&gt; tag
- * @sources: (element-type Gda.DataModel): a list of #GdaDataModel
+ * @sources: (element-type Gda.DataModel) (nullable): a list of #GdaDataModel
  * @error: a place to store errors, or %NULL
  *
  * Note: this method may set the "source" custom string property
@@ -786,14 +786,13 @@ gda_utility_holder_load_attributes (GdaHolder *holder, xmlNodePtr node, GSList *
  * alphanumeric character with the string "__gdaXX" where XX is the hex. representation
  * of the non alphanumeric char.
  *
- * Returns: a new string
+ * Returns: (transfer full): a new string
  */
 gchar *
 gda_text_to_alphanum (const gchar *text)
 {
        GString *string;
        const gchar* ptr = text;
-       gchar *ret;
 
        /*g_print ("%s (%s) ", __FUNCTION__, text);*/
        string = g_string_new ("");
@@ -807,10 +806,8 @@ gda_text_to_alphanum (const gchar *text)
                else
                        g_string_append_c (string, *ptr);
        }
-       ret = string->str;
-       g_string_free (string, FALSE);
-       /*g_print ("=>#%s#\n", ret);*/
-       return ret;
+
+       return g_string_free (string, FALSE);
 }
 
 /**
@@ -819,7 +816,7 @@ gda_text_to_alphanum (const gchar *text)
  *
  * Does the opposite of gda_text_to_alphanum(), in the same string 
  *
- * Returns: @text if conversion succeeded or %NULL if an error occurred
+ * Returns: (transfer full) (nullable): @text if conversion succeeded or %NULL if an error occurred
  */
 gchar *
 gda_alphanum_to_text (gchar *text)
@@ -918,7 +915,7 @@ dml_statements_check_select_structure (GdaConnection *cnc, GdaSqlStatement *sel_
  * use a primary key of @mtable. If @require_pk is %FALSE, then it will try to use a primary key of @mtable,
  * and if none is available, it will use all the columns of @mtable to compute a condition statement.
  *
- * Returns: a new #GdaSqlExpr, or %NULL if an error occurred.
+ * Returns: (transfer full) (nullable): a new #GdaSqlExpr, or %NULL if an error occurred.
  *
  * Since: 4.0.3
  */
@@ -1098,7 +1095,7 @@ gda_compute_unique_table_row_condition_with_cnc (GdaConnection *cnc, GdaSqlState
  * Computes a #GdaSqlExpr expression which can be used in the WHERE clause of an UPDATE
  * or DELETE statement when a row from the result of the @stsel statement has to be modified.
  *
- * Returns: a new #GdaSqlExpr, or %NULL if an error occurred.
+ * Returns: (transfer full) (nullable): a new #GdaSqlExpr, or %NULL if an error occurred.
  */
 GdaSqlExpr*
 gda_compute_unique_table_row_condition (GdaSqlStatementSelect *stsel, GdaMetaTable *mtable, gboolean 
require_pk, GError **error)
@@ -1111,9 +1108,9 @@ gda_compute_unique_table_row_condition (GdaSqlStatementSelect *stsel, GdaMetaTab
  * @cnc: a #GdaConnection
  * @select_stmt: a SELECT #GdaStatement (compound statements not handled)
  * @require_pk: TRUE if the created statement have to use a primary key
- * @insert_stmt: (nullable) (transfer full): a place to store the created INSERT statement, or %NULL
- * @update_stmt: (nullable) (transfer full): a place to store the created UPDATE statement, or %NULL
- * @delete_stmt: (nullable) (transfer full): a place to store the created DELETE statement, or %NULL
+ * @insert_stmt: (nullable) (transfer full) (out): a place to store the created INSERT statement, or %NULL
+ * @update_stmt: (nullable) (transfer full) (out): a place to store the created UPDATE statement, or %NULL
+ * @delete_stmt: (nullable) (transfer full) (out): a place to store the created DELETE statement, or %NULL
  * @error: (nullable): a place to store errors, or %NULL
  *
  * Creates an INSERT, an UPDATE and a DELETE statement from a SELECT statement
@@ -1338,7 +1335,7 @@ gda_compute_dml_statements (GdaConnection *cnc, GdaStatement *select_stmt, gbool
  * however that this #GdaSqlStatement does not select anything (ie it would be rendered as "SELECT FROM ... 
WHERE ...")
  * and before being usable, one needs to add some fields to actually select.
  *
- * Returns: a new #GdaStatement if no error occurred, or %NULL otherwise
+ * Returns: (transfer full) (nullable): a new #GdaStatement if no error occurred, or %NULL otherwise
  */
 GdaSqlStatement *
 gda_compute_select_statement_from_update (GdaStatement *update_stmt, GError **error)
@@ -1510,7 +1507,7 @@ null_param_unknown_foreach_func (GdaSqlAnyPart *part, NullData *data, GError **e
  * gda_rewrite_sql_statement_for_null_parameters:
  * @sqlst: (transfer full): a #GdaSqlStatement
  * @params: a #GdaSet to be used as parameters when executing @stmt
- * @out_modified: (nullable): a place to store the boolean which tells if @stmt has been modified or not, or 
%NULL
+ * @out_modified: (nullable) (out): a place to store the boolean which tells if @stmt has been modified or 
not, or %NULL
  * @error: a place to store errors, or %NULL
  *
  * Modifies @sqlst to take into account any parameter which might be %NULL: if @sqlst contains the
@@ -1525,7 +1522,7 @@ null_param_unknown_foreach_func (GdaSqlAnyPart *part, NullData *data, GError **e
  * NULL values in statements without having to rewrite statements, as database usually don't
  * consider that "xxx = NULL" is the same as "xxx IS NULL" when using parameters.
  *
- * Returns: (transfer full): the modified @sqlst statement, or %NULL if an error occurred
+ * Returns: (transfer full) (nullable): the modified @sqlst statement, or %NULL if an error occurred
  *
  * Since: 4.2.9
  */
@@ -1598,7 +1595,7 @@ gda_rewrite_sql_statement_for_null_parameters (GdaSqlStatement *sqlst, GdaSet *p
  * gda_rewrite_statement_for_null_parameters:
  * @stmt: (transfer none): a #GdaStatement
  * @params: a #GdaSet to be used as parameters when executing @stmt
- * @out_stmt: (transfer full) (nullable): a place to store the new #GdaStatement, or %NULL
+ * @out_stmt: (transfer full) (nullable) (out): a place to store the new #GdaStatement, or %NULL
  * @error: a place to store errors, or %NULL
  *
  * Modifies @stmt to take into account any parameter which might be %NULL: if @stmt contains the
@@ -1682,7 +1679,7 @@ static gboolean stmt_rewrite_update_default_keyword (GdaSqlStatementUpdate *upd,
  * if @remove is %FALSE and into <programlisting><![CDATA[INSERT INTO mytable (id) VALUES 
(23)]]></programlisting>
  * if @remove is %TRUE.
  *
- * Returns: a new #GdaSqlStatement, or %NULL if an error occurred
+ * Returns: (transfer full) (nullable): a new #GdaSqlStatement, or %NULL if an error occurred
  *
  * Since: 4.2
  */
@@ -2532,7 +2529,7 @@ static gboolean _sql_identifier_needs_quotes (const gchar *str);
  * For more information, see the <link linkend="gen:sql_identifiers">SQL identifiers and abstraction</link> 
and
  * <link linkend="information_schema:sql_identifiers">SQL identifiers in meta data</link> sections.
  *
- * Returns: the representation of @id ready to be used in SQL statement, as a new string,
+ * Returns: (transfer full) (nullable): the representation of @id ready to be used in SQL statement, as a 
new string,
  *          or %NULL if @id is in a wrong format
  *
  * Since: 4.0.3
@@ -3313,7 +3310,7 @@ gda_parse_formatted_time (const gchar *value, gchar sep)
  *
  * Accepted date format is "YYYY-MM-DDTHH:MM:SS[.ms][TZ]" where TZ is +hour or -hour
  *
- * Returns: a new #GDateTime if @value has been successfully parsed as a valid timestamp (see 
g_date_valid()). The returned instance should be freed using g_date_time_unref().
+ * Returns: (transfer full): a new #GDateTime if @value has been successfully parsed as a valid timestamp 
(see g_date_valid()). The returned instance should be freed using g_date_time_unref().
  */
 GDateTime*
 gda_parse_iso8601_timestamp (const gchar *value)
@@ -3335,7 +3332,7 @@ gda_parse_iso8601_timestamp (const gchar *value)
  * This function is similar to gda_parse_iso8601_timestamp() (with @first being @G_DATE_YEAR, @second being 
@G_DATE_MONTH,
  * @third being @G_DATE_DAY and @sep being '-') but allows one to specify the expected date format.
  *
- * Returns: (nullable): a new #GDateTime if @value has been successfully parsed as a valid date (see 
g_date_valid()).
+ * Returns: (nullable) (transfer full): a new #GDateTime if @value has been successfully parsed as a valid 
date (see g_date_valid()).
  * 
  * Since: 5.2
  */
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]