Documentation problems in bootstrap.inc

This looks pretty good, thanks!

I can suggest a few more improvements:
a)

/**
- * Initialize PHP environment.
+ * Initializes PHP environment.

Should be Initializes the PHP...

b)

 /**
- * Loads the configuration and sets the base URL, cookie domain, and
- * session name correctly.
+ * Loads the configuration.
+ *
+ * Also sets the base URL, cookie domain, and session name correctly.
  */

This could maybe use more elaboration - as a one-line description, "loads the configuration" leaves me asking: what configuration? Maybe "Loads the site configuration from settings.php" or whatever it does. Also, probably "correctly" is not necessary at the end. Remember, these one-line descriptions are used for many things on api.drupal.org and are not always seen in the context of the file they're in, etc.

c)

+ * The filename, whether provided, cached, or retrieved
  * from the database, is only returned if the file exists.

Not very good wrapping - first line should be longer.

d)

+ * @return
+ *   If $name is omitted, an array of all header names, that have been set.

No comma before "that"

e)

+ * @param $only_default
+ *   (optional) If TRUE and headers have already be sent, send only the
+ *   specified header.

be -> been

f) You might just leave the t() documentation alone, as it is being completely reworked in another issue:
#997884: t() documentation overhaul

g) Regarding those boostrap phase functions, one thing we could do is make them, e.g.:

 /**
  * Bootstraps the settings.php configuration.
  *
  * Sets up the script environment and loads settings.php.
  */
 function _drupal_bootstrap_configuration() {

That would be more in compliance with our standards than the current state of the doc headers.

Looking better! I see a couple more things that could be improved (these are not things you necessarily introduced, but things that should eventually be fixed):

a)

- *   Set to FALSE if you want to prevent this page to get cached.
+ *   (optional) Set to FALSE if you want to prevent this page to get cached.

"to get cached" should be "from being cached".

b)

  * @param $append
- *   Whether to append the value to an existing header or to replace it.
+ *   (optional) Whether to append the value to an existing header or to replace
+ *   it. Defaults to FALSE.

Since this is a true/false, and aside from the variable name $append it's not all that clear whether "append" or "replace" would correspond to true/false, I would prefer the wording: "TRUE to append the value to an existing header, or FALSE to replace the header." I think it's clearer.

c)

+ *   (optional) The header name to set. If ommitted, an array of all header
+ *   names, that have been set is returned.

There should not be a comma before "that"

d)

  * @param $obj
  *   The object to which the elements are appended.
  * @param $field
- *   The attribute of $obj whose value should be unserialized.
+ *   (optional) The attribute of $obj whose value should be unserialized.
+ *   Defaults to 'data'.
+ *
+ * @return
+ *   The object, with the appended elements.
  */
 function drupal_unpack($obj, $field = 'data') {

$obj should be renamed to $object, to comply with our coding standards. Since this is a local variable, it's considered a doc fix not an API change to change the param name for clarity.

e) Please just take out any changes to t() documentation and leave them out of this patch. They're being discussed elsewhere (see above).

f)

  * This is a wrapper function for watchdog() which automatically decodes an
  * exception.
@@ -1546,15 +1593,16 @@ function request_uri() {
  * @param $exception
  *   The exception that is going to be logged.
  * @param $message
- *   The message to store in the log. If empty, a text that contains all useful
- *   information about the passed in exception is used.
+ *   (optional) The message to store in the log. If empty, a text that contains
+ *   all useful information about the passed in exception is used.

first line: needs a comma before which
last two lines: "a text" should either be "text" or "a string", and passed-in should be hyphenated.

g)

+ *   (optional) Array of variables to replace in the message on display or NULL
+ *   if message is already translated or not possible to translate.

The first or needs a comma before it, I think, for clarity.

h)

+ * Sets a message which reflects the status of the performed operation.

which -> that

i)

+ * Calculates a base-64 encoded, URL-safe sha-256 hmac.

What's a hmac? If it's an acronym, should it be HMAC? I see it is HMAC down further.

j)

+ *   Depending on whether $property was set, the whole language object, or the
+ *   specified property.

no comma before or

Item (c) from comment #2 above is still there. So is item (a), and item (b) is not fixed either.... actually it looks like all the items in #2 are back.

t() doc changes are still in there too.

And I just noticed one more verb tense:

 /**
  * Define the critical hooks that force modules to always be loaded.

Define -> Defines

This is pretty good. One error:

- * Example for a fictitious site installed at
- * http://www.drupal.org:8080/mysite/test/ the 'settings.php' is searched in
- * the following directories:
+ * Example for a fictitious site installed
+ * http://www.drupal.org:8080/mysite/test/ the 'settings.php' is searched in the
+ * following directories:

The word "at" should not be removed here, I think?

Gracious, the doc in that function is a mess of grammar. I guess I'll file a separate issue on that. For now probably just replace the "at" where it was. Here's the separate issue:
#1071846: conf_path() doc needs cleanup

I don't have time to review the rest of this patch at the moment (got about 30% done).

We really should not do such big patches -- there's always some little problem and it derails the whole patch...

a)

 /**
- * Bootstrap database: Initialize database system and register autoload functions.
+ * Bootstraps the database
+ *
+ * Initializes the database system and registers autoload functions.
  */

Missing . at the end of the line. The same problem is in the next few functions as well, and here:

 /**
- * Central static variable storage.
+ * Stores static variables centrally
  *

b) Inconsistent use of SimpleTest vs. simpletest:

/**
+ * Generates a valid simpletest prefix.
+ *
  * Checks the current User-Agent string to see if this is an internal request
  * from SimpleTest. If so, returns the test prefix for this test.

It seems to be "simpletest" everywhere else in this file, so let's stick with that.

c) Extra hunks at the end of the patch file: aggregator.info and block.info

Well how about just making a problem-free patch for part of the file, and then a follow-up patch with another part? I don't really like to mark a patch as RTBC if it is fixing one error only to replace it with another error.

We're now doing this kind of cleanup on #1310084: [meta] API documentation cleanup sprint in larger batches.