Index: includes/database/database.inc =================================================================== RCS file: /cvs/drupal/drupal/includes/database/database.inc,v retrieving revision 1.103 diff -u -p -r1.103 database.inc --- includes/database/database.inc 20 Mar 2010 15:06:51 -0000 1.103 +++ includes/database/database.inc 20 Mar 2010 20:05:49 -0000 @@ -48,7 +48,6 @@ * database servers, so that is abstracted into db_query_range() arguments. * Finally, note the PDO-based ability to foreach() over the result set. * - * * All queries are passed as a prepared statement string. A * prepared statement is a "template" of a query that omits literal or variable * values in favor of placeholders. The values to place into those @@ -98,7 +97,6 @@ * considerably more secure against SQL injection than trying to remember * which values need quotation marks and string escaping and which don't. * - * * INSERT, UPDATE, and DELETE queries need special care in order to behave * consistently across all different databases. Therefore, they use a special * object-oriented API for defining a query structurally. For example, rather @@ -115,7 +113,6 @@ * while also allowing optimizations such as multi-insert queries. UPDATE and * DELETE queries have a similar pattern. * - * * Drupal also supports transactions, including a transparent fallback for * databases that do not support transactions. To start a new transaction, * simply call $txn = db_transaction(); in your own code. The transaction will @@ -126,7 +123,6 @@ * scope, that is, all relevant queries completed successfully. * * Example: - * * @code * function my_transaction_function() { * // The transaction opens here. @@ -166,7 +162,6 @@ * } * } * @endcode - * */ @@ -336,47 +331,39 @@ abstract class DatabaseConnection extend * Returns the default query options for any given query. * * A given query can be customized with a number of option flags in an - * associative array. - * - * target - The database "target" against which to execute a query. Valid + * associative array: + * - target: The database "target" against which to execute a query. Valid * values are "default" or "slave". The system will first try to open a * connection to a database specified with the user-supplied key. If one * is not available, it will silently fall back to the "default" target. * If multiple databases connections are specified with the same target, * one will be selected at random for the duration of the request. - * - * fetch - This element controls how rows from a result set will be + * - fetch: This element controls how rows from a result set will be * returned. Legal values include PDO::FETCH_ASSOC, PDO::FETCH_BOTH, * PDO::FETCH_OBJ, PDO::FETCH_NUM, or a string representing the name of a * class. If a string is specified, each record will be fetched into a new * object of that class. The behavior of all other values is defined by PDO. * See http://www.php.net/PDOStatement-fetch - * - * return - Depending on the type of query, different return values may be + * - return: Depending on the type of query, different return values may be * meaningful. This directive instructs the system which type of return * value is desired. The system will generally set the correct value * automatically, so it is extremely rare that a module developer will ever * need to specify this value. Setting it incorrectly will likely lead to * unpredictable results or fatal errors. Legal values include: - * - * Database::RETURN_STATEMENT - Return the prepared statement object for + * - Database::RETURN_STATEMENT: Return the prepared statement object for * the query. This is usually only meaningful for SELECT queries, where * the statement object is how one accesses the result set returned by the * query. - * - * Database::RETURN_AFFECTED - Return the number of rows affected by an + * - Database::RETURN_AFFECTED: Return the number of rows affected by an * UPDATE or DELETE query. Be aware that means the number of rows actually * changed, not the number of rows matched by the WHERE clause. - * - * Database::RETURN_INSERT_ID - Return the sequence ID (primary key) + * - Database::RETURN_INSERT_ID: Return the sequence ID (primary key) * created by an INSERT statement on a table that contains a serial * column. - * - * Database::RETURN_NULL - Do not return anything, as there is no + * - Database::RETURN_NULL: Do not return anything, as there is no * meaningful value to return. That is the case for INSERT queries on * tables that do not contain a serial column. - * - * throw_exception - By default, the database system will catch any errors + * - throw_exception: By default, the database system will catch any errors * on a query as an Exception, log it, and then rethrow it so that code * further up the call chain can take an appropriate action. To suppress * that behavior and simply return NULL on failure, set this option to @@ -548,7 +535,6 @@ abstract class DatabaseConnection extend * DatabaseStatementInterface may also be passed in order to allow calling * code to manually bind variables to a query. If a * DatabaseStatementInterface is passed, the $args array will be ignored. - * * It is extremely rare that module code will need to pass a statement * object to this method. It is used primarily for database drivers for * databases that require special LOB field handling. @@ -819,8 +805,7 @@ abstract class DatabaseConnection extend } /** - * Returns a DatabaseSchema object for manipulating the schema of this - * database. + * Returns a DatabaseSchema object for manipulating the schema. * * This method will lazy-load the appropriate schema library file. * @@ -1751,8 +1736,7 @@ class DatabaseTransaction { * @code * class DatabaseStatement_oracle extends PDOStatement implements DatabaseStatementInterface {} * @endcode - * - * …or implement their own class, but in that case they will also have to + * or implement their own class, but in that case they will also have to * implement the Iterator or IteratorArray interfaces before * DatabaseStatementInterface: * @code @@ -1802,12 +1786,12 @@ interface DatabaseStatementInterface ext * One of the PDO::FETCH_* constants. * @param $a1 * An option depending of the fetch mode specified by $mode: - * - for PDO::FETCH_COLUMN, it is the index of the column to fetch, - * - for PDO::FETCH_CLASS, it is the name of the class to create, and - * - for PDO::FETCH_INTO, it is the object to add the data to. + * - for PDO::FETCH_COLUMN, the index of the column to fetch + * - for PDO::FETCH_CLASS, the name of the class to create + * - for PDO::FETCH_INTO, the object to add the data to * @param $a2 - * In case of when mode is PDO::FETCH_CLASS, the optional arguments to - * pass to the constructor. + * If $mode is PDO::FETCH_CLASS, the optional arguments to pass to the + * constructor. */ // public function setFetchMode($mode, $a1 = NULL, $a2 = array()); @@ -2467,7 +2451,6 @@ function db_next_id($existing_id = 0) { * @{ */ - /** * Creates a new table from a Drupal table definition. * @@ -2784,7 +2767,7 @@ function db_change_field($table, $field, * @} End of "ingroup schemaapi". */ - /** +/** * Sets a session variable specifying the lag time for ignoring a slave server. */ function db_ignore_slave() { Index: includes/database/schema.inc =================================================================== RCS file: /cvs/drupal/drupal/includes/database/schema.inc,v retrieving revision 1.31 diff -u -p -r1.31 schema.inc --- includes/database/schema.inc 9 Mar 2010 11:39:07 -0000 1.31 +++ includes/database/schema.inc 20 Mar 2010 19:58:15 -0000 @@ -24,7 +24,6 @@ * the module defines. * * The following keys are defined: - * * - 'description': A string in non-markup plain text describing this table * and its purpose. References to other tables should be enclosed in * curly-brackets. For example, the node_revisions table @@ -33,7 +32,6 @@ * - 'fields': An associative array ('fieldname' => specification) * that describes the table's database columns. The specification * is also an array. The following specification parameters are defined: - * * - 'description': A string in non-markup plain text describing this field * and its purpose. References to other tables should be enclosed in * curly-brackets. For example, the node table vid field @@ -52,7 +50,6 @@ * datatypes will be used (e.g. on MySQL, TINYINT vs. INT vs. BIGINT). * 'normal', the default, selects the base type (e.g. on MySQL, * INT, VARCHAR, BLOB, etc.). - * * Not all sizes are available for all data types. See * DatabaseSchema::getFieldTypeMap() for possible combinations. * - 'not null': If true, no NULL values will be allowed in this @@ -71,10 +68,8 @@ * the precision (total number of significant digits) and scale * (decimal digits right of the decimal point). Both values are * mandatory. Ignored for other field types. - * * All parameters apart from 'type' are optional except that type * 'numeric' columns must specify 'precision' and 'scale'. - * * - 'primary key': An array of one or more key column specifiers (see below) * that form the primary key. * - 'unique keys': An associative array of unique keys ('keyname' => @@ -183,6 +178,7 @@ abstract class DatabaseSchema implements * The name of the table to explode. * @param $operator * The operator to apply on the 'table' part of the condition. + * * @return QueryConditionInterface * A DatabaseCondition object. */ @@ -209,6 +205,7 @@ abstract class DatabaseSchema implements * * @param $table * The name of the table in drupal (no prefixing). + * * @return * TRUE if the given table exists, otherwise FALSE. */ @@ -229,6 +226,7 @@ abstract class DatabaseSchema implements * @param $table_expression * An SQL expression, for example "simpletest%" (without the quotes). * BEWARE: this is not prefixed, the caller should take care of that. + * * @return * Array, both the keys and the values are the matching tables. */ @@ -250,6 +248,7 @@ abstract class DatabaseSchema implements * The name of the table in drupal (no prefixing). * @param $name * The name of the column. + * * @return * TRUE if the given column exists, otherwise FALSE. */ @@ -266,15 +265,15 @@ abstract class DatabaseSchema implements } /** - * Returns a mapping of Drupal schema field names to DB-native field types. - * - * Because different field types do not map 1:1 between databases, Drupal has - * its own normalized field type names. This function returns a driver-specific - * mapping table from Drupal names to the native names for each database. - * - * @return array - * An array of Schema API field types to driver-specific field types. - */ + * Returns a mapping of Drupal schema field names to DB-native field types. + * + * Because different field types do not map 1:1 between databases, Drupal has + * its own normalized field type names. This function returns a driver-specific + * mapping table from Drupal names to the native names for each database. + * + * @return array + * An array of Schema API field types to driver-specific field types. + */ abstract public function getFieldTypeMap(); /** @@ -284,6 +283,7 @@ abstract class DatabaseSchema implements * The table to be renamed. * @param $new_name * The new name for the table. + * * @throws DatabaseSchemaObjectDoesNotExistException * If the specified table doesn't exist. * @throws DatabaseSchemaObjectExistsException @@ -296,6 +296,7 @@ abstract class DatabaseSchema implements * * @param $table * The table to be dropped. + * * @return * TRUE if the table was successfully dropped, FALSE if there was no table * by that name to begin with. @@ -322,6 +323,7 @@ abstract class DatabaseSchema implements * adding a type 'serial' field, you MUST specify at least one key * or index including it in this array. See db_change_field() for more * explanation why. + * * @throws DatabaseSchemaObjectDoesNotExistException * If the specified table doesn't exist. * @throws DatabaseSchemaObjectExistsException @@ -336,6 +338,7 @@ abstract class DatabaseSchema implements * The table to be altered. * @param $field * The field to be dropped. + * * @return * TRUE if the field was successfully dropped, FALSE if there was no field * by that name to begin with. @@ -351,6 +354,7 @@ abstract class DatabaseSchema implements * The field to be altered. * @param $default * Default value to be set. NULL for 'default NULL'. + * * @throws DatabaseSchemaObjectDoesNotExistException * If the specified table or field doesn't exist. */ @@ -363,6 +367,7 @@ abstract class DatabaseSchema implements * The table to be altered. * @param $field * The field to be altered. + * * @throws DatabaseSchemaObjectDoesNotExistException * If the specified table or field doesn't exist. */ @@ -375,6 +380,7 @@ abstract class DatabaseSchema implements * The name of the table in drupal (no prefixing). * @param $name * The name of the index in drupal (no prefixing). + * * @return * TRUE if the given index exists, otherwise FALSE. */ @@ -387,6 +393,7 @@ abstract class DatabaseSchema implements * The table to be altered. * @param $fields * Fields for the primary key. + * * @throws DatabaseSchemaObjectDoesNotExistException * If the specified table doesn't exist. * @throws DatabaseSchemaObjectExistsException @@ -399,6 +406,7 @@ abstract class DatabaseSchema implements * * @param $table * The table to be altered. + * * @return * TRUE if the primary key was successfully dropped, FALSE if there was no * primary key on this table to begin with. @@ -414,6 +422,7 @@ abstract class DatabaseSchema implements * The name of the key. * @param $fields * An array of field names. + * * @throws DatabaseSchemaObjectDoesNotExistException * If the specified table doesn't exist. * @throws DatabaseSchemaObjectExistsException @@ -428,6 +437,7 @@ abstract class DatabaseSchema implements * The table to be altered. * @param $name * The name of the key. + * * @return * TRUE if the key was successfully dropped, FALSE if there was no key by * that name to begin with. @@ -443,6 +453,7 @@ abstract class DatabaseSchema implements * The name of the index. * @param $fields * An array of field names. + * * @throws DatabaseSchemaObjectDoesNotExistException * If the specified table doesn't exist. * @throws DatabaseSchemaObjectExistsException @@ -457,6 +468,7 @@ abstract class DatabaseSchema implements * The table to be altered. * @param $name * The name of the index. + * * @return * TRUE if the index was successfully dropped, FALSE if there was no index * by that name to begin with. @@ -522,6 +534,7 @@ abstract class DatabaseSchema implements * Optional keys and indexes specification to be created on the * table along with changing the field. The format is the same as a * table specification but without the 'fields' element. + * * @throws DatabaseSchemaObjectDoesNotExistException * If the specified table or source field doesn't exist. * @throws DatabaseSchemaObjectExistsException @@ -536,6 +549,7 @@ abstract class DatabaseSchema implements * The name of the table to create. * @param $table * A Schema API table definition array. + * * @throws DatabaseSchemaObjectExistsException * If the specified table already exists. */ @@ -557,6 +571,7 @@ abstract class DatabaseSchema implements * * @param $fields * An array of key/index column specifiers. + * * @return * An array of field names. */ @@ -580,6 +595,7 @@ abstract class DatabaseSchema implements * The comment string to prepare. * @param $length * Optional upper limit on the returned string length. + * * @return * The prepared comment. */