[libgda: 5/7] DB-doc: Improving documentation

[Daniel Espinosa Ortiz <despinosa src gnome org>]

commit 68438836da0054f69cf89f0a0a03d2a1bc134846
Author: Pavlo Solntsev <p sun fun gmail com>
Date:   Sat Mar 7 23:50:32 2020 -0600

    DB-doc: Improving documentation

 libgda/gda-db-column.c      | 58 +++++++++++++++++++++++++++++++++++++++++----
 libgda/gda-db-fkey.c        | 31 ++++++++++++++++++++++--
 libgda/gda-db-index-field.c | 23 ++++++++++++++++--
 libgda/gda-db-index.c       | 52 +++++++++++++++++++++++++++++++++++++---
 libgda/gda-db-table.c       | 42 +++++++++++++++++++++++++++++---
 libgda/gda-db-view.c        | 39 ++++++++++++++++++++++++++----
 6 files changed, 227 insertions(+), 18 deletions(-)
---
diff --git a/libgda/gda-db-column.c b/libgda/gda-db-column.c
index 44c284390..b1f25f2de 100644
--- a/libgda/gda-db-column.c
+++ b/libgda/gda-db-column.c
@@ -56,7 +56,25 @@ typedef struct
  *
  * This object represents a column of a table or a view. The column can be constracted manually
  * using API or generated from xml file together with other databse objects. See #GdaDbCatalog.
- * #GdaDbColumn implements #GdaDbBuildable interface for parsing xml file.
+ * #GdaDbColumn implements #GdaDbBuildable interface for parsing xml file. This is a typical example
+ * how the #GdaDbColumn API can be used.
+ *
+ * |[<!-- language="C" -->
+ * GdaDbTable *tproject = gda_db_table_new ();
+ * gda_db_base_set_name (GDA_DB_BASE (tproject), "Project");
+ *
+ * GdaDbColumn *pid = gda_db_column_new ();
+ * gda_db_column_set_name (pid, "id");
+ * gda_db_column_set_type (pid, G_TYPE_INT);
+ * gda_db_column_set_nnul (pid, TRUE);
+ * gda_db_column_set_autoinc (pid, TRUE);
+ * gda_db_column_set_unique (pid, TRUE);
+ * gda_db_column_set_pkey (pid, TRUE);
+ *
+ * gda_db_table_append_column (tproject, pid);
+ *
+ * g_object_unref (pid);
+ * ]|
  */
 
 /* All nodes in xml should be accessed using enum below */
@@ -124,6 +142,7 @@ static GParamSpec *properties [N_PROPS] = {NULL};
  *
  * Returns: New instance of #GdaDbColumn
  *
+ * Stability: Stable
  * Since: 6.0
  *
  */
@@ -567,6 +586,7 @@ _gda_db_column_set_type (GdaDbColumn *self,
  *
  * Returns: Column name as a string or %NULL.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 const gchar*
@@ -585,6 +605,7 @@ gda_db_column_get_name (GdaDbColumn *self)
  *
  * Set column name.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -604,6 +625,7 @@ gda_db_column_set_name (GdaDbColumn *self,
  *
  * Return of column type as #GType
  *
+ * Stability: Stable
  * Since: 6.0
  */
 GType
@@ -623,6 +645,7 @@ gda_db_column_get_gtype (GdaDbColumn *self)
  *
  * Returns: column type as a string or %NULL
  *
+ * Stability: Stable
  * Since: 6.0
  */
 const gchar*
@@ -638,8 +661,11 @@ gda_db_column_get_ctype (GdaDbColumn *self)
  * @self: a #GdaDbColumn instance
  * @type: #GType for column
  *
- * Set type of the column as a #GType
+ * Set type of the column as a #GType. For numeric type, #GDA_TYPE_NUMERIC should be used. Other
+ * types, e.g. %G_TYPE_FLOAT or %G_TYPE_DOUBLE can also be used but precision and scale should not be
+ * set. In this case appropriate types for DB implementation will be used, e.g. float4.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -661,6 +687,8 @@ gda_db_column_set_type (GdaDbColumn *self,
  * This value is ignore for column types except float or double.
  *
  * Returns: Current scale value
+ *
+ * Stability: Stable
  * Since: 6.0
  */
 guint
@@ -679,6 +707,7 @@ gda_db_column_get_scale (GdaDbColumn *self)
  * Scale is used for float number representation to specify a number of decimal digits.
  * This value is ignore for column types except float or double.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -698,6 +727,7 @@ gda_db_column_set_scale (GdaDbColumn *self,
  *
  * Returns: %TRUE if the column is primary key, %FALSE otherwise
  *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -713,6 +743,9 @@ gda_db_column_get_pkey (GdaDbColumn *self)
  * @self: a #GdaDbColumn object
  * @pkey: value to set
  *
+ * If @pkey is %TRUE, the given column will be marked with PRIMERY KEY flag
+ *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -732,6 +765,7 @@ gda_db_column_set_pkey (GdaDbColumn *self,
  *
  * Returns: %TRUE if value can be %NULL, %FALSE otherwise.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -746,7 +780,8 @@ gda_db_column_get_nnul (GdaDbColumn *self)
  * gda_db_column_set_nnul:
  * @self: a GdaDbColumn object
  * @nnul: value to set for nnul
- *
+ * If @nnul is %TRUE the column will be marked with NON NULL flag
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -766,6 +801,7 @@ gda_db_column_set_nnul (GdaDbColumn *self,
  *
  * Returns: %TRUE if column should be auto-incremented, %FALSE otherwise.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -783,6 +819,7 @@ gda_db_column_get_autoinc (GdaDbColumn *self)
  *
  * Set value for auto-incremented key.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -802,6 +839,7 @@ gda_db_column_set_autoinc (GdaDbColumn *self,
  *
  * Returns: %TRUE if column should have a unique value, %FALSE otherwise.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -819,6 +857,7 @@ gda_db_column_get_unique (GdaDbColumn *self)
  *
  * Set value for unique key.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -839,6 +878,7 @@ gda_db_column_set_unique (GdaDbColumn *self,
  * Returns: Column comment as a string.
  * %NULL is returned if comment is not set.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 const gchar*
@@ -857,6 +897,7 @@ gda_db_column_get_comment (GdaDbColumn *self)
  *
  * Set value for column comment.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -875,6 +916,7 @@ gda_db_column_set_comment (GdaDbColumn *self,
  *
  * Returns: Current value for column size.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 guint
@@ -892,6 +934,7 @@ gda_db_column_get_size (GdaDbColumn *self)
  *
  * Set value for column size. This is relevant only for string column type.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -911,6 +954,7 @@ gda_db_column_set_size (GdaDbColumn *self,
  *
  * Returns: Default value for the column as a string.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 const gchar*
@@ -926,6 +970,7 @@ gda_db_column_get_default (GdaDbColumn *self)
  * @self: a #GdaDbColumn instance
  * @value: default value to set for column as a string
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -946,6 +991,7 @@ gda_db_column_set_default (GdaDbColumn *self,
  *
  * Returns: Column check string
  *
+ * Stability: Stable
  * Since: 6.0
  */
 const gchar*
@@ -963,6 +1009,7 @@ gda_db_column_get_check (GdaDbColumn *self)
  *
  * Sets check string to the column.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -985,6 +1032,7 @@ gda_db_column_set_check (GdaDbColumn *self,
  *
  * Returns: %TRUE if successful, %FALSE otherwise.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -1093,6 +1141,7 @@ gda_db_column_prepare_create  (GdaDbColumn *self,
  *
  * Returns: %TRUE if success, %FALSE otherwise.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -1186,7 +1235,8 @@ gda_db_column_prepare_add (GdaDbColumn *self,
  *
  * Create new #GdaDbColumn instance from the corresponding #GdaMetaTableColumn
  * object. If %NULL is passed this function works exactly as
- * gda_db_column_new()
+ * gda_db_column_new(). Thie method is designed for internal use only and will be obsolete in the
+ * future.
  *
  * Returns: New object that should be freed with gda_db_column_free()
  */
diff --git a/libgda/gda-db-fkey.c b/libgda/gda-db-fkey.c
index df3c3ef77..be60d56fe 100644
--- a/libgda/gda-db-fkey.c
+++ b/libgda/gda-db-fkey.c
@@ -48,7 +48,18 @@ typedef struct
  * For generating database from xml file or for mapping
  * database to an xml file #GdaDbFkey holds information about
  * foregn keys with a convenient set of methods to manipulate them.
- * #GdaDbFkey implements #GdaDbBuildable interface for parsing xml file.
+ * #GdaDbFkey implements #GdaDbBuildable interface for parsing xml file. This is an example how
+ * #GdaDGdaDbFkey can be used:
+ *
+ * |[<!-- language="C" -->
+ * GdaDbFkey *fkey = gda_db_fkey_new ();
+ * gda_db_fkey_set_ref_table (fkey, "Project");
+ * gda_db_fkey_set_ondelete (fkey, GDA_DB_FKEY_RESTRICT);
+ * gda_db_fkey_set_onupdate (fkey, GDA_DB_FKEY_RESTRICT);
+ * gda_db_fkey_set_field (fkey, "project_id", "id");
+ *
+ * gda_db_table_append_fkey (temployee, fkey);
+ * ]|
  */
 
 static void gda_db_fkey_buildable_interface_init (GdaDbBuildableInterface *iface);
@@ -93,6 +104,7 @@ static const gchar *gdadbfkeynodes[GDA_DB_FKEY_N_NODES] = {
  *
  * Create a new #GdaDbFkey object.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 GdaDbFkey *
@@ -106,8 +118,11 @@ gda_db_fkey_new (void)
  * @metafkey: a #GdaMetaTableForeignKey instance
  *
  * Create a new instance from the corresponding meta object. If @metafkey is %NULL,
- * this function is identical to gda_db_fkey_new()
+ * this function is identical to gda_db_fkey_new(). This method is for internal use only and will be
+ * obsolete in the future.
  *
+ * Stability: Stable
+ * Since: 6.0
  */
 GdaDbFkey*
 gda_db_fkey_new_from_meta (GdaMetaTableForeignKey *metafkey)
@@ -390,6 +405,7 @@ gda_db_fkey_buildable_interface_init (GdaDbBuildableInterface *iface)
  * Return: ON DELETE action as a string. If the action is not set then the string corresponding to
  * NO_ACTION is returned.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 const gchar *
@@ -410,6 +426,7 @@ gda_db_fkey_get_ondelete (GdaDbFkey *self)
  *
  * Return: ON DELETE action as a #GdaDbFkeyReferenceAction.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 GdaDbFkeyReferenceAction
@@ -429,6 +446,7 @@ gda_db_fkey_get_ondelete_id (GdaDbFkey *self)
  *
  * Set action for ON_UPDATE
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -449,6 +467,7 @@ gda_db_fkey_set_onupdate (GdaDbFkey *self,
  *
  * Set action for ON_DELETE
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -468,6 +487,7 @@ gda_db_fkey_set_ondelete (GdaDbFkey *self,
  *
  * Returns: ON_UPDATE action as a string. Never %NULL
  *
+ * Stability: Stable
  * Since: 6.0
  */
 const gchar *
@@ -486,6 +506,7 @@ gda_db_fkey_get_onupdate (GdaDbFkey *self)
  *
  * Return: ON_UPDATE action as a #GdaDbFkeyReferenceAction
  *
+ * Stability: Stable
  * Since: 6.0
  */
 GdaDbFkeyReferenceAction
@@ -503,6 +524,7 @@ gda_db_fkey_get_onupdate_id (GdaDbFkey *self)
  * Return: Returns reference table name as a string or %NULL if table name
  * hasn't been set.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 const gchar *
@@ -522,6 +544,7 @@ gda_db_fkey_get_ref_table (GdaDbFkey *self)
  *
  * Set reference table
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -543,6 +566,7 @@ gda_db_fkey_set_ref_table (GdaDbFkey *self,
  * Returns: (element-type utf8) (transfer none): A const #GList of strings where each string
  * corresponds to a foreign key field or %NULL.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 const GList*
@@ -562,6 +586,7 @@ gda_db_fkey_get_field_name (GdaDbFkey *self)
  * Returns: (element-type utf8) (transfer none): A #GList of strings where each string corresponds
  * to a foreign key reference field or %NULL.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 const GList *
@@ -582,6 +607,7 @@ gda_db_fkey_get_ref_field (GdaDbFkey *self)
  *
  * All arguments should be valid strings.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -609,6 +635,7 @@ gda_db_fkey_set_field (GdaDbFkey  *self,
  *
  * Returns: %TRUE if no error or %FALSE otherwise.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
diff --git a/libgda/gda-db-index-field.c b/libgda/gda-db-index-field.c
index d8e0931cd..d32b98bf6 100644
--- a/libgda/gda-db-index-field.c
+++ b/libgda/gda-db-index-field.c
@@ -36,7 +36,8 @@ typedef struct
  * @include: libgda/libgda.h
  *
  * This object is a container for information needed to create an index for a table. After
- * population with information, it should be passed to the #GdaDbIndex instance.
+ * population with information, it should be passed to the #GdaDbIndex instance. See #GdaDbIndex
+ * section for the example.
  *
  */
 
@@ -49,6 +50,7 @@ G_DEFINE_TYPE_WITH_PRIVATE(GdaDbIndexField, gda_db_index_field, G_TYPE_OBJECT)
  *
  * Returns: (transfer full): A new instance of #GdaDbIndexField
  *
+ * Stability: Stable
  * Since: 6.0
  */
 GdaDbIndexField *
@@ -93,8 +95,11 @@ gda_db_index_field_init (GdaDbIndexField *self)
  * @self: an instance of #GdaDbIndexField
  * @column: column to add index to
  *
- * Only full name will be extracted from @column.
+ * Only full name will be extracted from @column. The @column instance should be freed using
+ * g_object_unref(). The instance @self take a copy of the @column object by increasing its
+ * referecne count.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -117,6 +122,7 @@ gda_db_index_field_set_column (GdaDbIndexField *self,
  *
  * Returns: (transfer none): A #GdaDbColumn where index should be added
  *
+ * Stability: Stable
  * Since: 6.0
  */
 GdaDbColumn *
@@ -136,6 +142,7 @@ gda_db_index_field_get_column (GdaDbIndexField *self)
  * "NOCASE", and "RTRIM" values. PostgreSQL, on the other hand expects a name of a callable object,
  * e.g. function.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -156,6 +163,7 @@ gda_db_index_field_set_collate (GdaDbIndexField *self,
  *
  * Returns: Collate value
  *
+ * Stability: Stable
  * Since: 6.0
  */
 const gchar *
@@ -170,6 +178,7 @@ gda_db_index_field_get_collate (GdaDbIndexField *self)
  * @self: object to use
  * @sorder: sort order to set
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -186,6 +195,7 @@ gda_db_index_field_set_sort_order (GdaDbIndexField *self,
  *
  * Returns: sort order as a #GdaDbIndexSortOrder object
  *
+ * Stability: Stable
  * Since: 6.0
  */
 GdaDbIndexSortOrder
@@ -195,6 +205,15 @@ gda_db_index_field_get_sort_order (GdaDbIndexField *self)
   return priv->mSortOrder;
 }
 
+/**
+ * gda_db_index_field_get_sort_order_str:
+ * @self: an instance of #GdaDbIndexField
+ *
+ * Returns: SORT ORDER string or %NULL
+ *
+ * Stability: Stable
+ * Since: 6.0
+ */
 const gchar *
 gda_db_index_field_get_sort_order_str (GdaDbIndexField *field)
 {
diff --git a/libgda/gda-db-index.c b/libgda/gda-db-index.c
index 38e5356ea..a4bd1890a 100644
--- a/libgda/gda-db-index.c
+++ b/libgda/gda-db-index.c
@@ -1,6 +1,6 @@
 /* gda-db-index.c
  *
- * Copyright (C) 2019 Pavlo Solntsev <p sun fun gmail com>
+ * Copyright (C) 2019-2020 Pavlo Solntsev <p sun fun gmail com>
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -40,6 +40,33 @@ typedef struct
  * @stability: Stable
  * @include: libgda/libgda.h
  *
+ * The object #GdaDBIndex holds information about index in a table. Just populate the information
+ * using index API and append to the #GdaDbTable  instance using gda_db_table_add_index(). This
+ * method executes all needed DB manopulations to add the atrget index to the DB. This can be
+ * illustarted by the following example:
+ *
+ * |[<!-- language="C" -->
+ * GdaDbIndex      *index = gda_db_index_new ();
+ * GdaDbIndexField *field = gda_db_index_field_new ();
+ * GdaDbColumn     *fcol  = gda_db_column_new ();
+ *
+ * gda_db_index_set_unique (index, TRUE);
+ * gda_db_base_set_name (GDA_DB_BASE (index), "MyIndex");
+ *
+ * gda_db_column_set_name (fcol, "name");
+ *
+ * gda_db_index_field_set_column (field, fcol);
+ * gda_db_index_field_set_sort_order (field, GDA_DB_INDEX_SORT_ORDER_ASC);
+ * gda_db_index_append_field (index, field);
+
+ * g_object_unref (fcol);
+ * g_object_unref (field);
+ *
+ * res = gda_db_table_add_index (new_table, index, fixture->cnc, TRUE, &error);
+ *
+ * if (!res)
+ *   g_print("Error during index addition\n");
+ * ]|
  */
 
 G_DEFINE_TYPE_WITH_PRIVATE (GdaDbIndex, gda_db_index, GDA_TYPE_DB_BASE)
@@ -86,6 +113,7 @@ gda_db_index_class_init (GdaDbIndexClass *klass)
  * If @val is %TRUE a "UNIQUE" will be added to the INDEX CREATE command, e.g.
  * CREATE UNIQUE INDEX ...
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -105,6 +133,7 @@ gda_db_index_set_unique (GdaDbIndex *self,
  *
  * Returns: state for UNIQUE. This method will abort if @self is %NULL
  *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -121,9 +150,10 @@ gda_db_index_get_unique (GdaDbIndex *self)
  * @field: a field to set
  *
  * Append to index filed to the current index instance, The @self object will recieve full
- * ownership of the field. After this call, the reference to the @field from the caller can be
- * destoyed by calling g_object_unref()
+ * ownership of the field. After this call, the reference count for @field will be increased and
+ * the instance of @fiels must be destroyed by calling g_object_unref()
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -165,6 +195,7 @@ gda_db_index_append_field  (GdaDbIndex *self,
  * @self: instance of #GdaDbIndex
  * @name: Name of the column where field should be removed.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -194,6 +225,9 @@ gda_db_index_remove_field (GdaDbIndex *self,
  * This function is thread safe, that is, @cnc will be locked.
  *
  * Returns: (transfer none) (nullable) (element-type Gda.DbIndexField): A list of #GdaDbIndexField
+ *
+ * Stability: Stable
+ * Since: 6.0
  */
 GSList *
 gda_db_index_get_fields (GdaDbIndex *self)
@@ -204,6 +238,18 @@ gda_db_index_get_fields (GdaDbIndex *self)
   return priv->mFieldList;
 }
 
+/**
+ * gda_db_index_drop:
+ * @self: an instance of #GdaDbIndex to work to drop
+ * @cnc: opened connection as the #GdaConnection
+ * @ifexists: flag for IF EXSISTS
+ * @error: an error storage
+ *
+ * Drop the index from the DB.
+ *
+ * Stability: Stable
+ * Since: 6.0
+ */
 gboolean
 gda_db_index_drop (GdaDbIndex *self,
                    GdaConnection *cnc,
diff --git a/libgda/gda-db-table.c b/libgda/gda-db-table.c
index 20d6ea8b0..db2a9682f 100644
--- a/libgda/gda-db-table.c
+++ b/libgda/gda-db-table.c
@@ -52,6 +52,13 @@ typedef struct
  * This object represents a table of a database. The table view can be constracted manually
  * using API or generated from xml file together with other databse objects. See #GdaDbCatalog.
  * #GdaDbTable implements #GdaDbBuildable interface for parsing xml file.
+ *
+ * #GdaDbTable can be used as a container to hold other objects, e.g. #GdaDbColumn, #GdaDbFkey and
+ * as soon as populated with al needed objects, a series of methods ccan be called:
+ * gda_db_table_create(), gda_db_table_add_column(), gda_db_table_add_index().
+ *
+ * To create table a method gda_db_table_create() can be called and to drop the table the
+ * gda_db_table_drop() can be called.
  */
 
 static void gda_db_table_buildable_interface_init (GdaDbBuildableInterface *iface);
@@ -97,6 +104,7 @@ static const gchar *gdadbtablenodes[GDA_DB_TABLE_N_NODES] = {
  *
  * Returns: New instance of #GdaDbTable.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 GdaDbTable *
@@ -351,6 +359,7 @@ gda_db_table_buildable_interface_init (GdaDbBuildableInterface *iface)
  * If @tablecomment is %NULL nothing is happened. @tablecomment will not be set
  * to %NULL.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -375,6 +384,7 @@ gda_db_table_set_comment (GdaDbTable *self,
  *
  * Set if the table should be temporary or not.  %FALSE is set by default.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -393,6 +403,7 @@ gda_db_table_set_is_temp (GdaDbTable *self,
  *
  * Returns: A comment string or %NULL if comment wasn't set.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 const char*
@@ -412,6 +423,7 @@ gda_db_table_get_comment (GdaDbTable *self)
  * If @self is %NULL, this function aborts. So check @self before calling this
  * method.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -433,6 +445,7 @@ gda_db_table_get_temp (GdaDbTable *self)
  *
  * Returns: %TRUE or %FALSE
  *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -462,6 +475,7 @@ gda_db_table_is_valid (GdaDbTable *self)
  * Returns: (element-type Gda.DbColumn) (transfer none): A list of #GdaDbColumn objects or %NULL
  * if the internal list is not set or if %NULL is passed.
  *
+ * Stability: Stable
  * Since: 6.0
  *
  */
@@ -485,6 +499,7 @@ gda_db_table_get_columns (GdaDbTable *self)
  * Returns: (transfer none) (element-type Gda.DbFkey): A list of #GdaDbFkey objects or %NULL if
  * the internal list is not set or %NULL is passed
  *
+ * Stability: Stable
  * Since: 6.0
  */
 GList*
@@ -505,6 +520,7 @@ gda_db_table_get_fkeys (GdaDbTable *self)
  *
  * Returns: %TRUE if table is temporary, %FALSE otherwise.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -528,6 +544,7 @@ gda_db_table_get_is_temp (GdaDbTable *self)
  *
  * Returns: %TRUE if no error occured and %FALSE otherwise.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -620,7 +637,8 @@ _gda_db_compare_column_meta (GdaMetaTableColumn *a,
  * @error: error container
  *
  * With this method object @obj in the database available through @cnc will be updated using
- * ADD_COLUMN operation with information stored in @self.
+ * ADD_COLUMN operation with information stored in @self. This method is designed for internal use
+ * only and should not be used for the new code. It will be obsolete.
  *
  * Returns: %TRUE if no error and %FALSE otherwise
  */
@@ -721,6 +739,7 @@ on_error:
  *
  * Returns: %TRUE if successful, %FALSE otherwise
  *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -773,6 +792,7 @@ gda_db_table_create (GdaDbTable *self,
  *
  * Append @column to the internal list of columns
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -794,6 +814,7 @@ gda_db_table_append_column (GdaDbTable *self,
  *
  * Append @fkey to the internal list of columns
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -815,6 +836,9 @@ gda_db_table_append_fkey (GdaDbTable *self,
  * @error: An error holder
  *
  * This method performs rename operation on the table
+ *
+ * Stability: Stable
+ * Since: 6.0
  */
 gboolean
 gda_db_table_rename (GdaDbTable *old_name,
@@ -883,6 +907,7 @@ on_error:
  *
  * Returns: %TRUE if no error occures and %FALSE otherwise
  *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -901,6 +926,8 @@ gda_db_table_add_column (GdaDbTable *self,
   g_return_val_if_fail(GDA_IS_CONNECTION (cnc), FALSE);
   g_return_val_if_fail(error == NULL || *error == NULL, FALSE);
 
+  const gchar *strtype;
+
   if (!gda_connection_is_opened (cnc))
     {
       g_set_error (error, GDA_DB_TABLE_ERROR, GDA_DB_TABLE_CONNECTION_NOT_OPENED,
@@ -930,7 +957,10 @@ gda_db_table_add_column (GdaDbTable *self,
                                           error, "/COLUMN_DEF_P/COLUMN_NAME"))
     goto on_error;
 
-  if (!gda_server_operation_set_value_at (op, gda_db_column_get_ctype(col),
+  strtype = gda_server_provider_get_default_dbms_type (gda_connection_get_provider (cnc),
+                                                       cnc, gda_db_column_get_gtype(col));
+
+  if (!gda_server_operation_set_value_at (op, strtype,
                                           error, "/COLUMN_DEF_P/COLUMN_TYPE"))
     goto on_error;
 
@@ -992,6 +1022,7 @@ on_error:
  *
  * Returns: %TRUE if no error and %FALSE otherwise.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -1065,6 +1096,7 @@ on_error:
  *
  * Returns: %TRUE if no error and %FALSE otherwise.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -1169,8 +1201,12 @@ on_error:
  * @self: a #GdaDbTable instance
  * @constr a constraint string to append
  *
- * Since: 6.0
+ * Adds globat table constraint. It will be added to the sql string by the provider implementation
+ * if it supports it. Usually, table constraint is very complex and the current method just append
+ * a list of constraints to the sql string.
  *
+ * Stability: Stable
+ * Since: 6.0
  */
 void
 gda_db_table_append_constraint (GdaDbTable *self,
diff --git a/libgda/gda-db-view.c b/libgda/gda-db-view.c
index 57c3c214a..75562ef48 100644
--- a/libgda/gda-db-view.c
+++ b/libgda/gda-db-view.c
@@ -43,7 +43,21 @@ typedef struct
  *
  * This object represents a view of a database. The view can be constracted manually
  * using API or generated from xml file together with other databse objects. See #GdaDbCatalog.
- * #GdaDbView implements #GdaDbBuildable interface for parsing xml file.
+ * #GdaDbView implements #GdaDbBuildable interface for parsing xml file. This is typical example
+ * how #GdaDbView can be used
+ *
+ * |[<!-- language="C" -->
+ *
+ *  GdaDbView *myview = gda_db_view_new ();
+ *  gda_db_base_set_name (GDA_DB_BASE (myview), "MyView");
+ *  gda_db_view_set_istemp (myview, FALSE);
+ *  gda_db_view_set_defstring (myview, "SELECT name, project_id FROM NewEmployee");
+ *
+ *  res = gda_db_view_create (myview, fixture->cnc, TRUE, &error);
+ *
+ *  if (!res)
+ *    GDA_PGSQL_ERROR_HANDLE (error);
+ *  ]|
  */
 
 static void gda_db_view_buildable_interface_init (GdaDbBuildableInterface *iface);
@@ -87,8 +101,9 @@ static GParamSpec *properties [N_PROPS] = {NULL};
 /**
  * gda_db_view_new:
  *
- * Returns: A new instance of #GdaDbView.
+ * Returns: (transfer full): A new instance of #GdaDbView.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 GdaDbView*
@@ -330,6 +345,8 @@ gda_db_view_buildable_interface_init (GdaDbBuildableInterface *iface)
  * @self: a #GdaDbView object
  *
  * Returns: %TRUE if the view is temporary, %FALSE otherwise
+ *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -345,6 +362,7 @@ gda_db_view_get_istemp (GdaDbView *self)
  * @self: a #GdaDbView object
  * @temp: value to set
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -362,6 +380,8 @@ gda_db_view_set_istemp (GdaDbView *self,
  *
  * Returns: %TRUE if th view should be created with "IF NOT EXISTS" key, %FALSE
  * otherwise
+ *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -377,6 +397,7 @@ gda_db_view_get_ifnoexist (GdaDbView *self)
  * @self: a #GdaDbView object
  * @noexist: a value to set
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -393,6 +414,8 @@ gda_db_view_set_ifnoexist (GdaDbView *self,
  * @self: a #GdaDbView object
  *
  * Returns: view definition string
+ *
+ * Stability: Stable
  * Sinc: 6.0
  */
 const gchar*
@@ -408,6 +431,7 @@ gda_db_view_get_defstring (GdaDbView *self)
  * @self: a #GdaDbView object
  * @str: view definition string to set. Should be valid SQL string
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
@@ -427,6 +451,7 @@ gda_db_view_set_defstring (GdaDbView *self,
  * Returns: %TRUE if the current view should replace the existing one in the
  * database, %FALSE otherwise.
  *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -443,11 +468,12 @@ gda_db_view_get_replace (GdaDbView *self)
  * @self: a #GdaDbView object
  * @replace: a value to set
  *
+ * Stability: Stable
  * Since: 6.0
  */
 void
 gda_db_view_set_replace (GdaDbView *self,
-                          gboolean replace)
+                        gboolean replace)
 {
   g_return_if_fail (self);
   GdaDbViewPrivate *priv = gda_db_view_get_instance_private (self);
@@ -471,6 +497,7 @@ gda_db_view_set_replace (GdaDbView *self,
  *
  * Returns: %TRUE if no error, %FASLE otherwise
  *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean
@@ -542,8 +569,10 @@ on_error:
  * @op: #GdaServerOperation instance to populate
  * @error: error container
  *
- * Populate @op with information needed to perform CREATE_VIEW operation.
+ * Populate @op with information needed to perform CREATE_VIEW operation. This method was desgned
+ * for internal use and will be obsolete in the future. Do not use it for the new code.
  *
+ * Stability: Stable
  * Returns: %TRUE if succeeded and %FALSE otherwise.
  */
 gboolean
@@ -596,6 +625,8 @@ gda_db_view_prepare_create (GdaDbView *self,
  * This method call DDL comands to drop the view. 
  *
  * Returns: %TRUE if everything is ok and %FALSE otherwise.
+ *
+ * Stability: Stable
  * Since: 6.0
  */
 gboolean