GNOME.org
 

[libgda] doc: Documentation update for GdaDb module.

commit 7efb6ddb9c72073a580896d4c7c779c7748fc726
Author: Pavlo Solntsev <p sun fun gmail com>
Date:   Thu Jun 4 14:50:10 2020 -0500

    doc: Documentation update for GdaDb module.

 doc/C/libgda/libgda-6.0-docs.xml     |  5 ++++-
 doc/C/libgda/libgda-6.0-sections.txt | 27 +++++++++++++++++----------
 doc/C/libgda/libgda.types.in         |  1 +
 libgda/gda-db-catalog.c              |  8 ++++----
 libgda/gda-db-column.c               |  3 ++-
 libgda/gda-db-column.h               |  1 +
 libgda/gda-db-fkey.c                 |  3 ++-
 libgda/gda-db-index.c                | 13 +++++++++----
 libgda/gda-db-index.h                |  5 -----
 libgda/gda-db-table.c                | 10 +++++-----
 libgda/gda-db-table.h                |  5 +++--
 libgda/gda-db-view.c                 |  2 +-
 libgda/gda-ddl-modifiable.c          | 16 ++++++++--------
 13 files changed, 57 insertions(+), 42 deletions(-)
---
diff --git a/doc/C/libgda/libgda-6.0-docs.xml b/doc/C/libgda/libgda-6.0-docs.xml
index 55a1bd315..e0958941e 100644
--- a/doc/C/libgda/libgda-6.0-docs.xml
+++ b/doc/C/libgda/libgda-6.0-docs.xml
@@ -121,15 +121,18 @@
       <xi:include href="xml/gda-attributes-manager.xml"/>
     </chapter>
 
-    <chapter id="DB Catalog">
+    <chapter id="DDL and DB Catalog">
       <title>DB Catalog</title>
       <xi:include href="xml/gda-db-base.xml"/>
       <xi:include href="xml/gda-db-buildable.xml"/>
+      <xi:include href="xml/gda-ddl-modifiable.xml"/>
       <xi:include href="xml/gda-db-column.xml"/>
       <xi:include href="xml/gda-db-catalog.xml"/>
       <xi:include href="xml/gda-db-fkey.xml"/>
       <xi:include href="xml/gda-db-table.xml"/>
       <xi:include href="xml/gda-db-view.xml"/>
+      <xi:include href="xml/gda-db-index.xml"/>
+      <xi:include href="xml/gda-db-index-field.xml"/>
     </chapter>
 
     <chapter id="Statement">
diff --git a/doc/C/libgda/libgda-6.0-sections.txt b/doc/C/libgda/libgda-6.0-sections.txt
index 22ebd62d5..8933aef5e 100644
--- a/doc/C/libgda/libgda-6.0-sections.txt
+++ b/doc/C/libgda/libgda-6.0-sections.txt
@@ -33,7 +33,6 @@ gda_db_index_get_unique
 gda_db_index_append_field
 gda_db_index_remove_field
 gda_db_index_get_fields
-gda_db_index_drop
 </SECTION>
 
 <SECTION>
@@ -41,7 +40,7 @@ gda_db_index_drop
 <TITLE>GdaDbIndexField</TITLE>
 GDA_TYPE_DB_INDEX_FIELD
 GdaDbIndexSortOrder
-GdaDbIndexCollate
+GdaDbIndexField
 gda_db_index_field_new
 gda_db_index_field_set_column
 gda_db_index_field_get_column
@@ -49,7 +48,6 @@ gda_db_index_field_set_collate
 gda_db_index_field_get_collate
 gda_db_index_field_set_sort_order
 gda_db_index_field_get_sort_order
-gda_db_index_field_get_collate_str
 gda_db_index_field_get_sort_order_str
 </SECTION>
 
@@ -151,16 +149,11 @@ gda_db_table_append_column
 gda_db_table_get_columns
 gda_db_table_append_fkey
 gda_db_table_get_fkeys
-gda_db_table_create
 gda_db_table_prepare_create
 gda_db_table_update
 gda_db_table_append_constraint
-gda_db_table_add_column
-gda_db_table_add_index
-gda_db_table_drop
 gda_db_table_error_quark
 gda_db_table_get_is_temp
-gda_db_table_rename
 gda_db_table_set_is_temp
 </SECTION>
 
@@ -180,8 +173,6 @@ gda_db_view_set_istemp
 gda_db_view_get_replace
 gda_db_view_set_replace
 gda_db_view_prepare_create
-gda_db_view_create
-gda_db_view_drop
 </SECTION>
 
 <SECTION>
@@ -215,6 +206,22 @@ GDA_TYPE_COLUMN
 gda_column_get_type
 </SECTION>
 
+<SECTION>
+<FILE>gda-ddl-modifiable</FILE>
+<TITLE>GdaDdlModifiable</TITLE>
+GdaDdlModifiable
+GdaDdlModifiableError
+gda_ddl_modifiable_create
+gda_ddl_modifiable_drop
+gda_ddl_modifiable_rename
+<SUBSECTION Standard>
+GDA_DDL_MODIFIABLE
+GDA_TYPE_DDL_MODIFIABLE
+GDA_IS_DDL_MODIFIABLE
+gda_ddl_modifiable_get_type
+GDA_DDL_MODIFIABLE_ERROR
+</SECTION>
+
 <SECTION>
 <FILE>gda-attributes-manager</FILE>
 <TITLE>Attributes manager</TITLE>
diff --git a/doc/C/libgda/libgda.types.in b/doc/C/libgda/libgda.types.in
index 535e3859a..ba0600dfd 100644
--- a/doc/C/libgda/libgda.types.in
+++ b/doc/C/libgda/libgda.types.in
@@ -69,3 +69,4 @@ gda_ddl_creator_get_type
 gda_ddl_table_get_type
 gda_ddl_column_get_type
 gda_ddl_buildable_get_type
+gda_ddl_modifiable_get_type
diff --git a/libgda/gda-db-catalog.c b/libgda/gda-db-catalog.c
index 2b8fd268d..04d590aa6 100644
--- a/libgda/gda-db-catalog.c
+++ b/libgda/gda-db-catalog.c
@@ -428,8 +428,8 @@ on_error:
  *
  * The given @xmlfile will be checked before parsing and %FALSE will be
  * returned if fails. The @xmlfile will be validated internally using
- * gda_db_catalog_validate_to_file() or gda_db_catalog_validate_to_path() methods.
- * The same methods can be used to validate xmlfile before parsing it.
+ * gda_db_catalog_validate_file_from_path(). he same method can be used to validate xmlfile
+ * before parsing it.
  */
 gboolean
 gda_db_catalog_parse_file_from_path (GdaDbCatalog *self,
@@ -825,7 +825,7 @@ gda_db_catalog_append_view (GdaDbCatalog *self,
  * After population @self with all data this method may be
  * called to trigger code and modify user database. This is the main
  * method to work with database. For retrieving information from database to an
- * xml file use gda_db_catalog_parse_cnc() and gda_db_buildable_write_xml().
+ * xml file use gda_db_catalog_parse_cnc() and gda_db_buildable_write_node().
  *
  * Connection can be added as a property using g_object_set() call and should be opened to use
  * this method. See gda_connection_open() method for reference.
@@ -968,7 +968,7 @@ gda_db_catalog_write_to_file (GdaDbCatalog *self,
  *
  * Save content of @self to a user friendly xml file.
  *
- * Returns: %TRUE is no error, %FLASE otherwise.
+ * Returns: %TRUE is no error, %FALSE otherwise.
  *
  * Since: 6.0
  */
diff --git a/libgda/gda-db-column.c b/libgda/gda-db-column.c
index ae3f772b0..0ace540e8 100644
--- a/libgda/gda-db-column.c
+++ b/libgda/gda-db-column.c
@@ -1075,6 +1075,7 @@ gda_db_column_set_check (GdaDbColumn *self,
  * gda_db_column_prepare_create:
  * @self: a #GdaDbColumn instance
  * @op: a #GdaServerOperation instance to update for TABLE_CREATE operation
+ * @order: Order number for the column
  * @error: a #GError container
  *
  * This method populate @op with information stored in @self.
@@ -1286,7 +1287,7 @@ gda_db_column_prepare_add (GdaDbColumn *self,
  * object. If %NULL is passed this function works exactly as
  * gda_db_column_new().
  *
- * Returns: New object that should be freed with gda_db_column_free()
+ * Returns: New object that should be freed with g_object_unref()
  */
 GdaDbColumn*
 gda_db_column_new_from_meta (GdaMetaTableColumn *column)
diff --git a/libgda/gda-db-column.h b/libgda/gda-db-column.h
index 5ef759dc4..154085f7b 100644
--- a/libgda/gda-db-column.h
+++ b/libgda/gda-db-column.h
@@ -41,6 +41,7 @@ struct _GdaDbColumnClass
 /**
  * GdaDbColumnError:
  * @GDA_DB_COLUMN_ERROR_TYPE: Set if wrong column type was given in the xml file.
+ * @GDA_DB_COLUMN_ERROR_WRONG_OPERATION: Wrong operation requested
  *
  * Values used to describe the source of the error.
  */
diff --git a/libgda/gda-db-fkey.c b/libgda/gda-db-fkey.c
index bd881bb2a..63f8a74db 100644
--- a/libgda/gda-db-fkey.c
+++ b/libgda/gda-db-fkey.c
@@ -49,7 +49,7 @@ typedef struct
  * 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. This is an example how
- * #GdaDGdaDbFkey can be used:
+ * #GdaDbFkey can be used:
  *
  * |[<!-- language="C" -->
  * GdaDbFkey *fkey = gda_db_fkey_new ();
@@ -628,6 +628,7 @@ gda_db_fkey_set_field (GdaDbFkey  *self,
  * gda_db_fkey_prepare_create:
  * @self: a #GdaDbFkey instance
  * @op: a #GdaServerOperation to populate
+ * @i: Order number
  * @error: error container
  *
  * Prepare @op object for execution by populating with information stored in @self.
diff --git a/libgda/gda-db-index.c b/libgda/gda-db-index.c
index 6f2458aad..f8118a3ec 100644
--- a/libgda/gda-db-index.c
+++ b/libgda/gda-db-index.c
@@ -43,15 +43,18 @@ 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
+ * The object #GdaDbIndex holds information about index in a table. Just populate the information
+ * using index API, set table as property, execute gda_ddl_modifiable_create() method. This
+ * method executes all needed DB manopulations to add the target index to the DB. This can be
  * illustarted by the following example:
  *
  * |[<!-- language="C" -->
+ * GdaDbTable *table = gda_db_table_new();
+ * // Populate table as needed.
  * GdaDbIndex      *index = gda_db_index_new ();
  * GdaDbIndexField *field = gda_db_index_field_new ();
  * GdaDbColumn     *fcol  = gda_db_column_new ();
+ * GError *error = NULL;
  *
  * gda_db_index_set_unique (index, TRUE);
  * gda_db_base_set_name (GDA_DB_BASE (index), "MyIndex");
@@ -65,7 +68,9 @@ typedef struct
  * g_object_unref (fcol);
  * g_object_unref (field);
  *
- * res = gda_db_table_add_index (new_table, index, fixture->cnc, TRUE, &error);
+ * g_object_set (index, "table", table, NULL);
+ *
+ * res = gda_ddl_modifiable_create (GDA_DDL_MODIFIABLE(index), cnc, NULL, &error);
  *
  * if (!res)
  *   g_print("Error during index addition\n");
diff --git a/libgda/gda-db-index.h b/libgda/gda-db-index.h
index a018ad0b2..667a20413 100644
--- a/libgda/gda-db-index.h
+++ b/libgda/gda-db-index.h
@@ -60,11 +60,6 @@ void              gda_db_index_remove_field (GdaDbIndex *self, const gchar *name
 
 GSList           *gda_db_index_get_fields   (GdaDbIndex *self);
 
-//gboolean          gda_db_index_drop (GdaDbIndex *self,
-                                     //GdaConnection *cnc,
-                                     //gboolean ifexists,
-                                     //GError **error);
-
 G_END_DECLS
 
 #endif /* end of include guard: GDA-DB-INDEX_H */
diff --git a/libgda/gda-db-table.c b/libgda/gda-db-table.c
index c7b180737..f23027ce4 100644
--- a/libgda/gda-db-table.c
+++ b/libgda/gda-db-table.c
@@ -55,11 +55,10 @@ typedef struct
  * #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().
+ * as soon as populated with all needed objects the table can be created using
+ * gda_ddl_modifiable_create(),
  *
- * 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.
+ * To delete the table a method gda_ddl_modifiable_drop() can be called.
  */
 
 static void gda_db_table_buildable_interface_init (GdaDbBuildableInterface *iface);
@@ -555,6 +554,7 @@ gda_db_table_get_is_temp (GdaDbTable *self)
  * gda_db_table_prepare_create:
  * @self: a #GdaDbTable instance
  * @op: an instance of #GdaServerOperation to populate.
+ * @ifnotexists: Set it to TRUE if "IF NOT EXISTS" should be added
  * @error: error container
  *
  * Populate @op with information stored in @self. This method sets @op to execute CREATE_TABLE
@@ -967,7 +967,7 @@ on_error:
 /**
  * gda_db_table_append_constraint:
  * @self: a #GdaDbTable instance
- * @constr a constraint string to append
+ * @constr: a constraint string to append
  *
  * Adds global 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
diff --git a/libgda/gda-db-table.h b/libgda/gda-db-table.h
index f4d44a536..686758c3c 100644
--- a/libgda/gda-db-table.h
+++ b/libgda/gda-db-table.h
@@ -43,7 +43,8 @@ struct _GdaDbTableClass {
 /**
  * GdaDbTableError:
  * @GDA_DB_TABLE_COLUMN_EMPTY: Table doesn't contain columns
- *
+ * @GDA_DB_TABLE_CONNECTION_NOT_OPENED: Closed connection was passed as parameter
+ * @GDA_DB_TABLE_SERVER_OPERATION: Error related to #GdaServerOperation
  */
 typedef enum {
     GDA_DB_TABLE_COLUMN_EMPTY,
@@ -80,7 +81,7 @@ void            gda_db_table_append_fkey (GdaDbTable *self,
                                           GdaDbFkey *fkey);
 
 void            gda_db_table_append_constraint (GdaDbTable *self,
-                                                const gchar *constraint);
+                                                const gchar *constr);
 
 G_END_DECLS
 
diff --git a/libgda/gda-db-view.c b/libgda/gda-db-view.c
index ba5002fbf..a8074472d 100644
--- a/libgda/gda-db-view.c
+++ b/libgda/gda-db-view.c
@@ -433,7 +433,7 @@ gda_db_view_set_ifnoexist (GdaDbView *self,
  * Returns: view definition string
  *
  * Stability: Stable
- * Sinc: 6.0
+ * Since: 6.0
  */
 const gchar*
 gda_db_view_get_defstring (GdaDbView *self)
diff --git a/libgda/gda-ddl-modifiable.c b/libgda/gda-ddl-modifiable.c
index a57489eba..4e7ae7609 100644
--- a/libgda/gda-ddl-modifiable.c
+++ b/libgda/gda-ddl-modifiable.c
@@ -26,7 +26,7 @@
 G_DEFINE_QUARK (gda_ddl_modifiable_error, gda_ddl_modifiable_error)
 
 /**
- * SECTION:gda-ddl-operation
+ * SECTION:gda-ddl-modifiable
  * @title: GdaDdlModifiable
  * @short_description: Interface to peform DDL operation
  * @see_also: #GdaDbTable, #GdaDbView, #GdaDbIndex, #GdaDbColumn
@@ -34,11 +34,11 @@ G_DEFINE_QUARK (gda_ddl_modifiable_error, gda_ddl_modifiable_error)
  * @include: libgda/libgda.h
  *
  * This interface should be used to perform some DDL opration using objects that implement it.
- * This interface is implemented by #GdaDbTable, #GdaDbColumn, #GdaDbIndex, and #GdaDbView. Calling
- * gda_ddl_modifiable_create() on #GdaDbColumn operation will execute ADD COLUMN operation. The
- * should pass a pointer to instance of GdaDbTable as user_data where column will be added (cretaed).
+ * Calling gda_ddl_modifiable_create() on #GdaDbColumn operation will execute ADD COLUMN
+ * operation. The user should pass a pointer to instance of #GdaDbTable as user_data where
+ * column will be added (cretaed).
  *
- * If the underlying object does not implement the operation, then FALSE is returned and the error
+ * If the underlying object does not implement the operation, then %FALSE is returned and the error
  * is set.
  */
 
@@ -53,7 +53,7 @@ gda_ddl_modifiable_default_init (GdaDdlModifiableInterface *iface)
 
 /**
  * gda_ddl_modifiable_create:
- * @self: Instance of GdaDdlModifiable
+ * @self: Instance of #GdaDdlModifiable
  * @cnc: Opened connection
  * @user_data: Additional information provided by the user
  * @error: Error holder
@@ -90,7 +90,7 @@ gda_ddl_modifiable_create (GdaDdlModifiable *self,
 
 /**
  * gda_ddl_modifiable_drop:
- * @self: Instance of GdaDdlModifiable
+ * @self: Instance of #GdaDdlModifiable
  * @cnc: Opened connection
  * @user_data: Additional information provided by the user
  * @error: Error holder
@@ -125,7 +125,7 @@ gda_ddl_modifiable_drop (GdaDdlModifiable *self,
 
 /**
  * gda_ddl_modifiable_rename:
- * @self: Instance of GdaDdlModifiable
+ * @self: Instance of #GdaDdlModifiable
  * @cnc: Opened connection
  * @user_data: Additional information provided by the user
  * @error: Error holder
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]