[libgda/LIBGDA_5.2] Improved GdaData documentation

[Vivien Malerba <vivien src gnome org>]

commit 0d663fcd5a0a64ea891d26807a7ad64aabce933e
Author: Daniel Espinosa <esodan gmail com>
Date:   Wed Sep 3 03:52:05 2014 -0500

    Improved GdaData documentation

 doc/mallard/gda-vala/C/record-class.page |   17 +++++++++--------
 doc/mallard/gda-vala/C/table-class.page  |    6 +++---
 2 files changed, 12 insertions(+), 11 deletions(-)
---
diff --git a/doc/mallard/gda-vala/C/record-class.page b/doc/mallard/gda-vala/C/record-class.page
index d37e169..8797125 100644
--- a/doc/mallard/gda-vala/C/record-class.page
+++ b/doc/mallard/gda-vala/C/record-class.page
@@ -20,7 +20,7 @@
   <code>Record</code> class is an implementation of <code>DbRecord</code> interface. It uses GDA to get 
access to a database's row in a table.
   </p>
   <p>
-  In order to load data, you need to set a <code>Gda.Connection</code>, a table and a key. Then 
<code>update()</code> method execute a SELECT command using the key to find the required row in the table.
+  In order to load data, you need to set a <code>Gda.Connection</code>, a table and a key. Then 
<code>update()</code> method execute a <code>SELECT</code> command using the key to find the required row in 
the table.
   </p>
   <section id="record-uml">
   <title>Record class UML definition</title>
@@ -34,7 +34,7 @@
   <title>Using a Record class to access a row in a table</title>
   <listing>
   <desc>
-  This codes initiate a Record class, set a table to use, a key and a connection in order to call update()
+  This codes initiate a Record class, set a table to use, a key and a connection in order to call 
<code>update()</code>.
   </desc>
   <code mime="text/x-c++src">
   var r = new Record ();
@@ -46,13 +46,13 @@
   r.update ();
   </code>
   </listing>
-  <p>In the above code, connection is opened before to be set to <code>Record.connection</code> property. 
You need to setup a <code>Table</code> class to set to <code>Record.table</code> property, but just set 
<code>Table.name</code> property to the table's name is required. Use <code>Record.set_key_value()</code> 
method to set the value to the column used in the table as the primary key and to allow <code>update()</code> 
method to find the correct row (the WHERE clause in SELECT statement), if more than one key exists you must 
set it; you must know the column and type of value to set.
+  <p>In the above code, connection is opened before to be set to <code>Record.connection</code> property. 
You need to setup a <code>Table</code> class to set to <code>Record.table</code> property, but just set 
<code>Table.name</code> property to the table's name is required. Use <code>Record.set_key_value()</code> 
method to set the value to the column used in the table as the primary key and to allow <code>update()</code> 
method to find the correct row (the <code>WHERE</code> clause in <code>SELECT</code> statement), if more than 
one key exists you must set it; you must know the column and type of value to set.
   </p>
   </section>
   <section id="record-append">
   <title>Using a Record class to add a new row in a table</title>
   <listing>
-  <desc>This code set up a row to be added to a database's table</desc>
+  <desc>This code set up a row to be added to a database's table:</desc>
   <code mime="text/x-c++src">
   var r = new Record ();
   var t = new Table ();
@@ -68,13 +68,13 @@
   In the above code a new row will be added. Create a new <code>Record</code> object, set a table to add a 
new row to; use <code>Record.set_field_value()</code> to set values to columns in the table, you must know 
columns and data type to set. At the end call <code>Record.save()</code> to add the new row.
   </p>
   <p>
-  <code>Record.set_field_value()</code> doesn't know if the columns and type is correct, just store the 
value to used in an INSERT statement; if key is set by database engine it will be added automatically, if not 
you must set it in order to execute <code>save()</code> with no errors.
+  <code>Record.set_field_value()</code> doesn't know if the columns and type is correct, just store the 
value to used in an <code>INSERT</code> statement; if key is set by database engine it will be added 
automatically, if not you must set it in order to execute <code>save()</code> with no errors.
   </p>
   </section>
   <section>
   <title>Update data in a row</title>
   <p>
-  Once you have set a key and a table to a <code>Record</code> object, you can call 
<code>Record.set_field_value()</code> to change row's column's values, once done, you can call 
<code>Record.save()</code> to call an UPDATE command and update database's row/column values.
+  Once you have set a key and a table to a <code>Record</code> object, you can call 
<code>Record.set_field_value()</code> to change row's column's values, once done, you can call 
<code>Record.save()</code> to call an <code>UPDATE</code> command and update database's row/column values.
   </p>
   <listing>
   <title>Updating columns' values</title>
@@ -82,6 +82,7 @@
   <code>
   var r = new Record ();
   r.connection = connection;
+  /* Set a value to the key you want to use to select the correct row */
   r.set_key_value ("id", 1);
   r.set_field_value ("name", "Jack Swan");
   r.save ();
@@ -113,11 +114,11 @@
   <code>Record</code> class could be used as base for others. Is useful to wrap 
<code>Record.set_field_value()</code> into your class property to hide database access.
   </p>
   <note style="tip">
-  <p>Use <code>try{}</code><code> catch{}</code> to avoid warnings for unhandled error</p>
+  <p>Use <code>try{}</code> <code> catch{}</code> to avoid warnings for unhandled error.</p>
   </note>
   <listing>
   <desc>
-  This code declares a new class MyRecord derived from Record.
+  This code declares a new class <code>MyRecord</code> derived from <code>Record</code>.
   </desc>
   <code mime="text/x-c++src">
   class MyRecord : Record
diff --git a/doc/mallard/gda-vala/C/table-class.page b/doc/mallard/gda-vala/C/table-class.page
index 89cae32..24f9a61 100644
--- a/doc/mallard/gda-vala/C/table-class.page
+++ b/doc/mallard/gda-vala/C/table-class.page
@@ -20,7 +20,7 @@
   <code>Table</code> class is an implementation of <code>DbTable</code> interface. It uses GDA to get access 
to a database's table description.
   </p>
   <p>
-  In order to load data, you need to set a <code>Gda.Connection</code> and a table's name. Then 
<code>update()</code> method will introspect table information using GDA's MetaStore object and executing 
SELECT commands to retrive meta data to strore store it, you don't need to call update() again unless your 
table definition has changed.
+  In order to load data, you need to set a <code>Gda.Connection</code> and a table's name. Then 
<code>update()</code> method will introspect table information using GDA's MetaStore object and executing 
<code>SELECT</code> commands to retrive meta data to strore store it, you don't need to call 
<code>update()</code> again unless your table definition has changed.
   </p>
   <section id="table-uml">
   <title>Table class UML definition</title>
@@ -91,10 +91,10 @@
   </code>
   </listing>
   <p>
-  In the above code a new table will be added. Create a new <code>Table</code> object, set its name and 
connection, use <code>Table.set_field()</code> to set column definitions. You must create 
<code>DbFieldInfo</code> objects, setting its name, type and attributes is enough to be set in a table. If 
your column must be a PRIMARY KEY you must set <code>DbFieldInfo.attributes</code> to 
<code>DbFieldInfo.Attribute.PRIMARY_KEY</code>; if it is autoincrement key you must use <code>|</code> 
operator to add a <code>DbFieldInfo.Attribute.AUTO_INCREMENT</code> attribute.
+  In the above code a new table will be added. Create a new <code>Table</code> object, set its name and 
connection, use <code>Table.set_field()</code> to set column definitions. You must create 
<code>DbFieldInfo</code> objects, setting its name, type and attributes is enough to be set in a table. If 
your column must be a <code>PRIMARY_KEY</code> you must set <code>DbFieldInfo.attributes</code> to 
<code>DbFieldInfo.Attribute.PRIMARY_KEY</code>; if it is autoincrement key you must use <code>|</code> 
operator to add a <code>DbFieldInfo.Attribute.AUTO_INCREMENT</code> attribute.
   </p>
   <p>
-  If the column will refer to a column in other table as a foreign key you must set 
<code>DbFieldInfo.fkey</code>. ForeignKey object is used for column's foreign keys.
+  If the column will refer to a column in other table as a foreign key you must set 
<code>DbFieldInfo.fkey</code>. <code>DbFieldInfo.ForeignKey</code> object is used for column's foreign keys.
   </p>
   </section>
   <section>