Add namespace information to database.inc @return documentation

I meant let's not use the interface here for consistency -- the object is called Select\Query. not SelectQuery, not any more. Aside from that, very very awesome and through work, more than I expected by fixing the human readable parts too, I only caught the @return parts being broken.

Thanks for the patches! One thing needs to be fixed though: we use "bool" to stand for a Boolean return value:
http://drupal.org/node/1354#param-return-data-type

And extra credit if you can add a blank line between param/return, such as here:

* @param $conjunction
  *   The conjunction to use for query conditions (AND, OR or XOR).
- * @return Condition
+ * @return Drupal\Core\Database\Condition

Thanks for the new patch! There are still a couple of things that need fixing:

a)

+ * @return Drupal\Core\Database\Query\Select
+ *   An new SelectQuery object for this connection.
  */
 function db_select($table, $alias = NULL, array $options = array()) {

Should be "A new Select object...".

b)

+ * @return Drupal\Core\Database\Condition
  */
 function db_or() {

@return statements need an extra line of description added. [same for _and() and _xor() methods]

#8 - a was not entirely fixed in this patch... Or maybe this is a different spot that I missed in the last review:

+ * @return Drupal\Core\Database\Query\Select
  *   A new SelectQuery object for this connection.
  */
 function db_select($table, $alias = NULL, array $options = array()) {

SelectQuery -> Select

I think your explanations for or/and are fine! The db_or() return value explanation ends in .. though instead of just one ., so that needs to be fixed.

Also, db_condition() needs an explanation line in the @return [missed that one in the last review too apparently].

... I realize that I'm generally unhappy with all of the new first line summaries of these functions though. With the old class names, a summary like " Returns a new MergeQuery object for the active database." was pretty clear, because the class name MergeQuery told you it was a query-related object. But the new class names are not specific that way. Actually, the new names violate our coding standards for naming classes (point 10 on http://drupal.org/node/608152 says "Classes and interfaces should have names that stand alone to tell what they do without having to refer to the namespace"... When and why were these changed??????

Anyway, the first line summaries are unclear with such non-specific names and I'd rather see them changed... for instance,

Returns a new MergeQuery object for the active database.

should be something more like:

Creates a new Merge query object for the active database.

which would at least tell us what is happening if the class names are going to violate our standards.

I just filed #1809930: [meta] Many core class names violate naming standards

I'm sorry, but I think we should actually postpone this until #1809930: [meta] Many core class names violate naming standards is addressed, because a number of these changes will not be necessary (the class names will be changed back to InsertQuery etc.).

Three years later, this include file has completely been surpassed and many of these issues have been taken care of, so I think I'll just close this.