There is a minor spelling error in the description of the return value of the db_set_active() function's documentation. The error is in the 6.x, 5.x, and 4.7.x versions. For convenience, I've attached patches for all three versions that fix that error, a punctuation error, and formatting error.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

oadaeh’s picture

I guess there's still an issue with attachments and previews.

jhodgdon’s picture

Status: Active » Needs work

I believe there should be a comma before "or" in your proposed fix, and not after "FALSE". Should be:

The name of the previously active database, or FALSE if none was found.

If you supply new patches, please set the status to "needs review", which indicates there is a patch that needs to be reviewed.

oadaeh’s picture

Status: Needs work » Needs review

If I were to write the sentence in its complete form, it would read:
"The return value will be either the name of the previously active database or FALSE, if none was found."

The "or" is between "the previously active database" and "FALSE" not between "The name of the previously active database" and "FALSE if none was found".

The "if none was found" phrase is a parenthetical element and is not necessary for the sentence to be technically correct and understood. Therefore, it is set aside with the comma.

Another way to write it would be:
"The name of the previously active database or, if none was found, FALSE."

Then there would need to be a comma after the "or", but there would not be a comma after the "or" the way the sentence currently is.

I also have a bit of an issue with the phrase "if none was found", but I'm not coming up with anything better, and all I was really trying to do was to change "non" to "none".

Thank for reminding me about the 'needs review' setting. I keep forgetting to set that.

jhodgdon’s picture

I still think it needs another comma -- to me, it's two clauses put together with a conjunction, and clearer with a comma. Just like the comma I put before "and" in that previous sentence. I'm fine with two commas. I'm not happy with it how it is.

oadaeh’s picture

The comma before your "and" is also incorrect. The only time you add a comma to two clauses that are joined with a conjunction is when the two clauses are independent clauses, which requires both a subject and a verb. The clause following the "and" is not an independent clause, lacking a subject, and therefore, it is incorrect to place a comma before the "and". The "FALSE" following the "or" in the patch is also not an independent clause, lacking a verb, and it is also not correct to add a comma before the "or".

http://www.bartleby.com/141/
http://grammar.ccc.commnet.edu/Grammar/clauses.htm
http://grammar.ccc.commnet.edu/Grammar/commas.htm

Placing two commas in the sentence describing the return value is even more wrong than just leaving all commas out.

jhodgdon’s picture

I don't want to get into a long argument about commas, but separating independent clauses is far from their only use. Strunk and White is also not Drupal's official reference for usage, nor is http://grammar.ccc.commnet.edu/Grammar/commas.htm -- but check out #7 on that page.

Anyway. I do not want to argue this any more.

Please just make the return value into two sentences, or reword it in another way, so that we don't have to have long and pointless grammar and punctuation lessons in the issue queue. I find the wording and punctuation in your original patch to be very awkward.

jhodgdon’s picture

Status: Needs review » Needs work
Issue tags: +Novice

A new patch for 6.x with better wording would be a good project for a novice doc contributor.

It would also be lovely if the doc were brought up to our doc standards for functions.
http://drupal.org/node/1354

jhodgdon’s picture

Status: Needs work » Closed (duplicate)

There's a new issue that points out a related issue with db_set_active, so let's fix it there:
#1184106: db_set_active doc issues