Clean up API docs for Test base classes in Simpletest module

Please confine this patch to API documentation -- no code lines. Thanks!

Aside from that, most of the patch looks good! A few things to fix up:

a)

+   * @param string|bool $status
+   *   Can be 'pass', 'fail', 'exception'.
+   *   TRUE is a synonym for 'pass', FALSE for 'fail'.

Wrapping -- this can all go on one line.

b) Maybe this information should be left in the first line (if it fits):

/**
-   * Check to see if a value is not false (not an empty string, 0, NULL, or FALSE).
+   * Checks whether a value is not FALSE.
+   *
+   * A 'not false' value is not an empty string, 0, NULL, or FALSE.

Same with the following function... Having it in the first line will help when scanning the method list. If you do need to move it, at least make the capitalization consistent ('not FALSE').

c)

* @param $message
-   *   The message to display along with the assertion.
+   *   (optional) The message to display along with the assertion. Defaults to
+   *   an empty string.
    * @param $group
-   *   The type of assertion - examples are "Browser", "PHP".
+   *   (optional) The type of assertion - examples are "Browser", "PHP".
+   *   Defaults to 'Other'.

Let's leave these changes out for now. There's a separate issue that's discussing wholesale changes to how the $message/$group parameters should be documented so it would be better to do it there:
#1457320: Document that t() should not be used for assertion message texts and groups

d)

+   * This method backups various current environment variables and resets them,

Backup is not a verb. It should be "backs up".

e)

/**
    * Constructor for UnitTestBase.
+   *
+   * @param string $test_id
+   *   (optional) The test ID.  Defaults to NULL.
    */
   function __construct($test_id = NULL) {

Should only be one space after . in this line. There's another one at

+   *   equeal.  Hence, a return of zero means that both the file size and file
+   *   names are equal.
    */
   protected function drupalCompareFiles($file1, $file2) {

f)

/**
-   * The value of the Drupal.settings JavaScript variable for the page currently loaded in the internal browser.
+   * The value of the Drupal.settings JavaScript variable for the page currently
+   * loaded in the internal browser.
    *
-   * @var Array
+   * @var array
    */
   protected $drupalSettings;

Needs one-line summary.

g)

/**
-   * The original user, before it was changed to a clean uid = 1 for testing purposes.
+   * The original user.
+   *
+   * This value is saved before it was changed to a clean uid = 1 for testing
+   * purposes.
    *
    * @var object
    */
   protected $originalUser = NULL;
 

There is a verb tense agreement problem in the new paragraph (is/was). The same problem is in the next few doc blocks.

h) Take care of the ??? in the patch.

That's about where I lost steam... it looks like this patch isn't done.

Um. We need a docs cleanup patch for the API Docs Cleanup effort. Please just provide a patch that doesn't mess with code. Thanks!

These issues are a lot of work with very little tangible payoff, so I'm closing the rest of them as "won't fix". Your efforts on working on this issue were appreciated... it was just my fault for starting a task that was very difficult to get right.

Let's instead put our effort into fixing and reviewing documentation that is really unclear and/or wrong, and I hope that the people who worked on these issues are not afraid to jump into a more reasonable issue!