[libgda] DdlModifiable: Adding documentation and check for opened connection

[Pavlo Solntsev <psolntsev src gnome org>]

commit e35bbbd9b152de65e6da2087da76b9f4fc80525b
Author: Pavlo Solntsev <p sun fun gmail com>
Date:   Wed Jun 3 22:54:34 2020 -0500

    DdlModifiable: Adding documentation and check for opened connection

 libgda/gda-ddl-modifiable.c | 66 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
---
diff --git a/libgda/gda-ddl-modifiable.c b/libgda/gda-ddl-modifiable.c
index a43814d23..a57489eba 100644
--- a/libgda/gda-ddl-modifiable.c
+++ b/libgda/gda-ddl-modifiable.c
@@ -21,6 +21,7 @@
 
 #define G_LOG_DOMAIN "GDA-ddl-modifiable"
 #include "gda-ddl-modifiable.h"
+#include <glib/gi18n-lib.h>
 
 G_DEFINE_QUARK (gda_ddl_modifiable_error, gda_ddl_modifiable_error)
 
@@ -37,6 +38,8 @@ G_DEFINE_QUARK (gda_ddl_modifiable_error, gda_ddl_modifiable_error)
  * 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).
  *
+ * If the underlying object does not implement the operation, then FALSE is returned and the error
+ * is set.
  */
 
 G_DEFINE_INTERFACE (GdaDdlModifiable, gda_ddl_modifiable, G_TYPE_OBJECT)
@@ -48,6 +51,20 @@ gda_ddl_modifiable_default_init (GdaDdlModifiableInterface *iface)
   /* add properties and signals to the interface here */
 }
 
+/**
+ * gda_ddl_modifiable_create:
+ * @self: Instance of GdaDdlModifiable
+ * @cnc: Opened connection
+ * @user_data: Additional information provided by the user
+ * @error: Error holder
+ *
+ * This method executes CREATE operation. That is, #GdaDbTable, #GdaDbIndex, and #GdaDbView
+ * implement corresponding CREATE TABLE | CREATE INDEX | CREATE VIEW operations. #GdaDbColumn
+ * implements ADD COLUMN operation as part of ALTER TABLE operation.
+ *
+ * Stability: Stable
+ * Since: 6.0
+ */
 gboolean
 gda_ddl_modifiable_create (GdaDdlModifiable *self,
                           GdaConnection *cnc,
@@ -59,10 +76,30 @@ gda_ddl_modifiable_create (GdaDdlModifiable *self,
   g_return_val_if_fail (GDA_IS_DDL_MODIFIABLE (self), FALSE);
   g_return_val_if_fail (GDA_IS_CONNECTION (cnc), FALSE);
 
+  if (!gda_connection_is_opened (cnc))
+    {
+      g_set_error (error, GDA_DDL_MODIFIABLE_ERROR,
+                   GDA_DDL_MODIFIABLE_CONNECTION_NOT_OPENED,
+                   _("Connection is not opened"));
+      return FALSE;
+    }
+
   iface = GDA_DDL_MODIFIABLE_GET_IFACE (self);
   return iface->create (self, cnc, user_data, error);
 }
 
+/**
+ * gda_ddl_modifiable_drop:
+ * @self: Instance of GdaDdlModifiable
+ * @cnc: Opened connection
+ * @user_data: Additional information provided by the user
+ * @error: Error holder
+ *
+ * Execute corresponding DROP operation
+ *
+ * Stability: Stable
+ * Since: 6.0
+ */
 gboolean
 gda_ddl_modifiable_drop (GdaDdlModifiable *self,
                         GdaConnection *cnc,
@@ -74,10 +111,31 @@ gda_ddl_modifiable_drop (GdaDdlModifiable *self,
   g_return_val_if_fail (GDA_IS_DDL_MODIFIABLE (self), FALSE);
   g_return_val_if_fail (GDA_IS_CONNECTION (cnc), FALSE);
 
+  if (!gda_connection_is_opened (cnc))
+    {
+      g_set_error (error, GDA_DDL_MODIFIABLE_ERROR,
+                   GDA_DDL_MODIFIABLE_CONNECTION_NOT_OPENED,
+                   _("Connection is not opened"));
+      return FALSE;
+    }
+
   iface = GDA_DDL_MODIFIABLE_GET_IFACE (self);
   return iface->drop (self, cnc, user_data, error);
 }
 
+/**
+ * gda_ddl_modifiable_rename:
+ * @self: Instance of GdaDdlModifiable
+ * @cnc: Opened connection
+ * @user_data: Additional information provided by the user
+ * @error: Error holder
+ *
+ * Execute corresponding RENAME operation. A lot of RENAME operations are not implemented by
+ * SQLite3 provider. In this case, the SQL object must be deleted and a new one should be created.
+ *
+ * Stability: Stable
+ * Since: 6.0
+ */
 gboolean
 gda_ddl_modifiable_rename (GdaDdlModifiable *self,
                           GdaConnection *cnc,
@@ -89,6 +147,14 @@ gda_ddl_modifiable_rename (GdaDdlModifiable *self,
   g_return_val_if_fail (GDA_IS_DDL_MODIFIABLE (self), FALSE);
   g_return_val_if_fail (GDA_IS_CONNECTION (cnc), FALSE);
 
+  if (!gda_connection_is_opened (cnc))
+    {
+      g_set_error (error, GDA_DDL_MODIFIABLE_ERROR,
+                   GDA_DDL_MODIFIABLE_CONNECTION_NOT_OPENED,
+                   _("Connection is not opened"));
+      return FALSE;
+    }
+
   iface = GDA_DDL_MODIFIABLE_GET_IFACE (self);
   return iface->rename (self, cnc, user_data, error);
 }