[libgda] Documentation updates regarding GdaSqlExpr

[Vivien Malerba <vivien src gnome org>]

commit cdda4d87f6154e888b39c852e087273605fc7d6b
Author: Vivien Malerba <malerba gnome-db org>
Date:   Sun Dec 5 15:42:16 2010 +0100

    Documentation updates regarding GdaSqlExpr

 doc/C/tmpl/gda-sql-statement.sgml              |    7 +++++-
 libgda/sql-parser/gda-statement-struct-parts.h |   26 ++++++++++++++++++++++++
 2 files changed, 32 insertions(+), 1 deletions(-)
---
diff --git a/doc/C/tmpl/gda-sql-statement.sgml b/doc/C/tmpl/gda-sql-statement.sgml
index ae4eddc..dd587e4 100644
--- a/doc/C/tmpl/gda-sql-statement.sgml
+++ b/doc/C/tmpl/gda-sql-statement.sgml
@@ -6,6 +6,10 @@ Structure which decomposes an SQL statement
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+  Please note that it is not advised to build #GdaSqlStatement structures directly, but rather
+  it is recommended to use the #GdaSqlBuilder object and its associated API.
+</para>
+<para>
 Every SQL statement can be decomposed in a #GdaSqlStatement structure. This is not a #GObject, but rather just a C structure
 which can be manipulated directly. The structure is a tree composed of several key structures which are show in the following diagram
 (even though it does not show, all structures "inherit" the #GdaSqlAnyPart structure which holds some basic information).
@@ -28,7 +32,8 @@ which can be manipulated directly. The structure is a tree composed of several k
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+  The #GdaSqlBuilder object which features some easy to use API to build #GdaSqlStatement structures
+  or #GdaStatement objects without having to worry about the details of #GdaSqlStatement's contents.
 </para>
 
 <!-- ##### SECTION Stability_Level ##### -->
diff --git a/libgda/sql-parser/gda-statement-struct-parts.h b/libgda/sql-parser/gda-statement-struct-parts.h
index d1961af..0325623 100644
--- a/libgda/sql-parser/gda-statement-struct-parts.h
+++ b/libgda/sql-parser/gda-statement-struct-parts.h
@@ -44,6 +44,32 @@ typedef struct _GdaSqlSelectOrder GdaSqlSelectOrder;
 /*
  * Any Expression
  */
+/**
+ * GdaSqlExpr:
+ * @any: inheritance structure
+ * @value: a #GValue, or %NULL. Please see specific note about this field. 
+ * @param_spec: a #GdaSqlParamSpec, or %NULL if this is not a variable
+ * @func: not %NULL if expression is a function or aggregate
+ * @cond: not %NULL if expression is a condition or an operation
+ * @select: not %NULL if expression is a sub select statement (#GdaSqlStatementSelect or #GdaSqlStatementCompound)
+ * @case_s: not %NULL if expression is a CASE WHEN ... expression
+ * @cast_as: not %NULL if expression must be cast to another data type
+ * @value_is_ident: Please see specific note about the @value field
+ *
+ * This structure contains any expression, either as a value (the @value part is set),
+ * a variable (the @param_spec is set), or as other types of expressions.
+ *
+ * Note 1 about the @value field: if the expression represents a string value in the SQL statement,
+ * the string itself must be represented as it would be in the actual SQL, ie. it should be
+ * escaped (accordingly to the escaping rules of the database which will use the SQL). For 
+ * example a string representing the <userinput>'joe'</userinput> value should be
+ * <userinput>"'joe'"</userinput> and not <userinput>"joe"</userinput>.
+ *
+ * Note 2 about the @value field: if the expression represents an SQL identifier (such as a table
+ * or field name), then the @value_is_ident should be set to %0x01, and @value should be a string
+ * which may contain double quotes around SQL identifiers which also are reserved keywords or which
+ * are case sensitive.
+ */
 struct _GdaSqlExpr {
 	GdaSqlAnyPart    any;
 	GValue          *value;