#807336 by jhodgdon, Berdir, Crell: Document thrown exceptions in database layer.

includes/database/database.inc

@@ -537,6 +537,8 @@ abstract class DatabaseConnection extends PDO {
    *   query builder and should not be set by a user. If there is an error,
    *   this method will return NULL and may throw an exception if
    *   $options['throw_exception'] is TRUE.
+   *
+   * @throws PDOException
    */
   public function query($query, array $args = array(), $options = array()) {
 
@@ -875,6 +877,8 @@ abstract class DatabaseConnection extends PDO {
    *   The name of the savepoint. The default, 'drupal_transaction', will roll
    *   the entire transaction back.
    *
+   * @throws DatabaseTransactionNoActiveException
+   *
    * @see DatabaseTransaction::rollback()
    */
   public function rollback($savepoint_name = 'drupal_transaction') {
@@ -912,6 +916,8 @@ abstract class DatabaseConnection extends PDO {
    *
    * If no transaction is already active, we begin a new transaction.
    *
+   * @throws DatabaseTransactionNameNonUniqueException
+   *
    * @see DatabaseTransaction
    */
   public function pushTransaction($name) {
@@ -942,6 +948,9 @@ abstract class DatabaseConnection extends PDO {
    * @param $name
    *   The name of the savepoint
    *
+   * @throws DatabaseTransactionNoActiveException
+   * @throws DatabaseTransactionCommitFailedException
+   *
    * @see DatabaseTransaction
    */
   public function popTransaction($name) {
@@ -1094,6 +1103,8 @@ abstract class DatabaseConnection extends PDO {
    * A direct commit bypasses all of the safety checks we've built on top of
    * PDO's transaction routines.
    *
+   * @throws DatabaseTransactionExplicitCommitNotAllowedException
+   *
    * @see DatabaseTransaction
    */
   public function commit() {
@@ -1468,6 +1479,9 @@ abstract class Database {
    *   "default".
    * @param $target
    *   The database target to open.
+   *
+   * @throws DatabaseConnectionNotDefinedException
+   * @throws DatabaseDriverNotSpecifiedException
    */
   final protected static function openConnection($key, $target) {
     if (empty(self::$databaseInfo)) {

includes/database/query.inc

@@ -535,6 +535,9 @@ class InsertQuery extends Query {
    *
    * @return
    *   TRUE if the validation was successful, FALSE if not.
+   *
+   * @throws FieldsOverlapException
+   * @throws NoFieldsException
    */
   public function preExecute() {
     // Confirm that the user did not try to specify an identical
@@ -782,6 +785,8 @@ class MergeQuery extends Query {
    *
    * @return
    *   TRUE if the validation was successful, FALSE if not.
+   *
+   * @throws InvalidMergeQueryException
    */
   public function preExecute() {
 
@@ -800,6 +805,8 @@ class MergeQuery extends Query {
    *   A status indicating the executed operation:
    *   - MergeQuery::STATUS_INSERT for an INSERT operation.
    *   - MergeQuery::STATUS_UPDATE for an UPDATE operation.
+   *
+   * @throws InvalidMergeQueryException
    */
   public function execute() {
     // If validation fails, simply return NULL.