[libgdamm] Small documentation improvements.

[Murray Cumming <murrayc src gnome org>]

commit 97b12a7cbb00e349c432825b53c66ab1cdec02c9
Author: Murray Cumming <murrayc murrayc com>
Date:   Sat Oct 16 22:29:06 2010 +0200

    Small documentation improvements.
    
    * libgda/src/libgda_docs.xml: Fix a typo that I fixed in libgda too.
    * libgda/src/sqlbuilder.[hg|ccg]: Small docs improvements.
    select_add_target_id(): Use _WRAP_METHOD() for this.
    * libgda/src/sqlexpr.hg: Added some overview documentation.
    * libgda/src/sqlstatement.hg: Added some overview documentation.

 ChangeLog                  |   10 ++++++++++
 libgda/src/libgda_docs.xml |    6 +++---
 libgda/src/sqlbuilder.ccg  |    5 -----
 libgda/src/sqlbuilder.hg   |   24 ++++++++++++++++++++----
 libgda/src/sqlexpr.hg      |    5 ++++-
 libgda/src/sqlstatement.hg |    3 ++-
 6 files changed, 39 insertions(+), 14 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 6ff5860..1096098 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,15 @@
 2010-10-16  Murray Cumming  <murrayc murrayc com>
 
+	Small documentation improvements.
+
+	* libgda/src/libgda_docs.xml: Fix a typo that I fixed in libgda too.
+	* libgda/src/sqlbuilder.[hg|ccg]: Small docs improvements. 
+	select_add_target_id(): Use _WRAP_METHOD() for this.
+	* libgda/src/sqlexpr.hg: Added some overview documentation.
+	* libgda/src/sqlstatement.hg: Added some overview documentation.
+
+2010-10-16  Murray Cumming  <murrayc murrayc com>
+
 	Doxyfile.in: Make more like the gtkmm one.
 
 	* docs/reference/Doxyfile.in: Minor unimportant changes, to match gtkmm.
diff --git a/libgda/src/libgda_docs.xml b/libgda/src/libgda_docs.xml
index fffc481..72d266d 100644
--- a/libgda/src/libgda_docs.xml
+++ b/libgda/src/libgda_docs.xml
@@ -1408,7 +1408,7 @@ to it using gda_holder_set_value() or gda_holder_take_value().
 
 <function name="gda_sql_builder_add_cond_v">
 <description>
-Builds a new expression which reprenents a condition (or operation).
+Builds a new expression which represents a condition (or operation).
 
 As a side case, if @ops_ids_size is 1,
 then @op is ignored, and the returned ID represents @op_ids[0] (this avoids any problem for example
@@ -6083,7 +6083,7 @@ supported).
 
 <function name="gda_sql_builder_add_cond">
 <description>
-Builds a new expression which reprenents a condition (or operation).
+Builds a new expression which represents a condition (or operation).
 
 Since: 4.2
 
@@ -8426,7 +8426,7 @@ Get the number of rows in the proxied data model
 
 <function name="gda_sql_builder_add_function">
 <description>
-Builds a new expression which reprenents a function applied to some arguments
+Builds a new expression which represents a function applied to some arguments
 
 Since: 4.2
 
diff --git a/libgda/src/sqlbuilder.ccg b/libgda/src/sqlbuilder.ccg
index aef199e..3a6110c 100644
--- a/libgda/src/sqlbuilder.ccg
+++ b/libgda/src/sqlbuilder.ccg
@@ -94,11 +94,6 @@ SqlBuilder::Id SqlBuilder::select_add_target(const Glib::ustring& table_name, co
   return gda_sql_builder_select_add_target(gobj(), table_name.c_str(), string_or_null(alias.c_str()));
 }
 
-SqlBuilder::Id SqlBuilder::select_add_target_id(Id table_id, const Glib::ustring& alias)
-{
-  return gda_sql_builder_select_add_target_id(gobj(), table_id, string_or_null(alias.c_str()));
-}
-
 SqlBuilder::Id SqlBuilder::select_join_targets(Id left_target_id, Id right_target_id, SqlSelectJoinType join_type, Id join_expr)
 {
   return gda_sql_builder_select_join_targets(gobj(), left_target_id, right_target_id, (GdaSqlSelectJoinType) join_type, join_expr);
diff --git a/libgda/src/sqlbuilder.hg b/libgda/src/sqlbuilder.hg
index 239cedb..e6d2847 100644
--- a/libgda/src/sqlbuilder.hg
+++ b/libgda/src/sqlbuilder.hg
@@ -42,7 +42,7 @@ _WRAP_GERROR(SqlError, GdaSqlError, GDA_SQL_ERROR)
  *
  * You may, for instance, pass the SqlBuilder directly to 
  * Connection::statement_execute_select_builder() or 
- * statement_execute_non_select_builder(). Or you may instead call 
+ * Connection::statement_execute_non_select_builder(). Or you may instead call 
  * get_statement() and use the resulting SqlStatement.
  *
  * During the building process, some pieces of the statement are constructed 
@@ -216,9 +216,7 @@ public:
   Id select_add_target(const Glib::ustring& table_name, const Glib::ustring& alias = Glib::ustring());
   _IGNORE(gda_sql_builder_select_add_target)
 
-  //For instance, to add a sub-query?
-  Id select_add_target_id(Id table_id, const Glib::ustring& alias = Glib::ustring());
-  _IGNORE(gda_sql_builder_select_add_target_id)
+  _WRAP_METHOD(Id select_add_target_id(Id table_id, const Glib::ustring& alias = Glib::ustring()), gda_sql_builder_select_add_target_id)
 
   /** Joins two targets in a SELECT statement.
    *
@@ -261,6 +259,24 @@ public:
   _WRAP_METHOD(void set_table(const Glib::ustring& table_name), gda_sql_builder_set_table)
   _WRAP_METHOD(void set_where(Id cond_id), gda_sql_builder_set_where)
 
+  //The documentation is hand-written to use doxygen's list/item syntax.
+  /** Valid only for: INSERT, UPDATE, SELECT statements.
+   * - For UPDATE: specifies that the field represented by @a field_id will be set to the value identified
+   * by @a value_id.
+   * - For SELECT: add a selected item to the statement, and if @a value_id is not %0, then use it as an
+   * alias
+   * - For INSERT: if @a field_id represents an SQL identifier (obtained using add_id()): then if
+   *  @a value_id is not %0 then specifies that the field represented by @a field_id will be set to the
+   * value identified by @a value_id, otherwise just specifies a named field to be given a value.
+   * If @a field_id represents a sub SELECT (obtained using add_sub_select()), then
+   * this method call defines the sub SELECT from which values to insert are taken.
+   * 
+   * See also add_field_value() and add_field_value_as_gvalue().
+   * 
+   * @newin{4,2}
+   * @param field_id The ID of the field's name or definition.
+   * @param value_id The ID of the value to set the field to, or %0.
+   */
   _WRAP_METHOD(void add_field_value_id(Id field_id, Id value_id = 0), gda_sql_builder_add_field_value_id)
 
   /** Specifies that the field represented by @a field_name will be set to the @a value.
diff --git a/libgda/src/sqlexpr.hg b/libgda/src/sqlexpr.hg
index d3ab29b..0d8d4b4 100644
--- a/libgda/src/sqlexpr.hg
+++ b/libgda/src/sqlexpr.hg
@@ -29,7 +29,10 @@ namespace Gnome
 namespace Gda
 {
 
-/** TODO
+//TODO: The C API seems to expect direct struct access as public API, 
+//but do apps ever need to use that API?
+/** This contains any expression, either as a value, a variable, or as other 
+ * types of expressions. 
  */
 class SqlExpr
 {
diff --git a/libgda/src/sqlstatement.hg b/libgda/src/sqlstatement.hg
index e155448..f3e7bc6 100644
--- a/libgda/src/sqlstatement.hg
+++ b/libgda/src/sqlstatement.hg
@@ -32,7 +32,8 @@ _WRAP_ENUM(SqlStatementType, GdaSqlStatementType)
 
 class Connection;
 
-/** TODO
+/** Every SQL statement can be decomposed in the SqlStatement tree structure.
+ * See the documentation for the underlying <a href="http://library.gnome.org/devel/libgda/unstable/libgda-4.0-GdaSqlStatement.html#libgda-4.0-GdaSqlStatement.description";>GdaSqlStatement</a>.
  */
 class SqlStatement
 {