anewt-developers team mailing list archive

[noreply@xxxxxxxxxxxxx]

------------------------------------------------------------
revno: 1725
committer: Wouter Bolsterlee <uws@xxxxxxxxx>
branch nick: anewt.uws
timestamp: Sun 2009-08-02 21:08:38 +0200
message:
  [database] Add more documentation
modified:
  database/connection.lib.php


--
lp:anewt
https://code.launchpad.net/~uws/anewt/anewt.uws

Your team Anewt developers is subscribed to branch lp:anewt.
To unsubscribe from this branch go to https://code.launchpad.net/~uws/anewt/anewt.uws/+edit-subscription.

=== modified file 'database/connection.lib.php'
--- database/connection.lib.php	2009-07-21 18:22:09 +0000
+++ database/connection.lib.php	2009-08-02 19:08:38 +0000
@@ -87,6 +87,12 @@
 
 	/** \{
 	 * \name Connection methods
+	 *
+	 * These methods can be used to connect and disconnect from the database.
+	 * Note that, by default, database connections automatically connect when
+	 * they are setup using AnewtDatabase::setup_connection(). If you do not
+	 * want this, set the \c autoconnect property to \c false when setting up
+	 * the connection.
 	 */
 
 	/**
@@ -144,6 +150,16 @@
 
 	/** \{
 	 * \name Query methods
+	 *
+	 * These methods provide a rich API to execute queries and retrieve
+	 * resulting rows. The basic functionality to prepare a query that can later
+	 * be executed is provided by prepare(), but several convenience methods are
+	 * available that cover the most frequent use cases, e.g. fetching all rows
+	 * from a result set.
+	 *
+	 * To build complex SQL queries, while still using the extensive type
+	 * checking this module offers, you can use create_sql_template() to obtain
+	 * an AnewtDatabaseSQLTemplate instance that you can fill manually.
 	 */
 
 	/**
@@ -427,6 +443,11 @@
 	 * The implementations of these methods in AnewtDatabaseConnection are
 	 * generic. Some of those methods are overridden in the database backend
 	 * specific subclasses.
+	 *
+	 * Note that it is often not the right approach to invoke these methods
+	 * yourself when building complex SQL queries. Creating an
+	 * AnewtDatabaseSQLTemplate with create_sql_template() and filling that
+	 * instead results in code that is much cleaner and more easy to read.
 	 */
 
 	/**