diff -u b/states_exercise.module b/states_exercise.module
--- b/states_exercise.module
+++ b/states_exercise.module
@@ -1,9 +1,8 @@
 <?php
-// $Id$
 
 /**
  * @file
- * Demonstrate as many #states features as possible.
+ * Provides a manual test suite for the #states API.
  */
 
 /**
@@ -32,6 +31,7 @@
     'access callback' => TRUE,
   );
 
+  // Test simple states.
   $items['states-exercise/simple'] = array(
     'type' => MENU_DEFAULT_LOCAL_TASK,
     'title' => 'States/conditions',
@@ -60,7 +60,7 @@
     $secondary_weight++;
   }
 
-  // Add tabs for testing operators.
+  // Test AND, OR and XOR states.
   foreach ($operators as $operator) {
     $weight++;
 
@@ -98,6 +98,7 @@
     }
   }
 
+  // Test mixed AND, OR and XOR states.
   $items["states-exercise/mixed"] = array(
     'type' => MENU_LOCAL_TASK,
     'title' => 'Conditions (mixed)',
@@ -111,8 +112,7 @@
 }
 
 /**
- * Attempt to demonstrate most permutations of #states.
- * This hopes to become a complete and exhaustive click-and-test suite.
+ * Menu callback; attempts to demonstrate all permutations of #states.
  */
 function states_exercise_exhaustive_states($form, &$form_state, $form_element) {
   // Secondary tabs might wrap to second line.
@@ -232,9 +232,10 @@
 }
 
 /**
- * Allows testing of multiple conditions from different dependees, ANDed, ORed
- * or XORed together.
- * TODO: test also AND, OR and XOR of "value" condition values.
+ * Menu callback; allows manual testing of multiple conditions from different
+ * dependees, ANDed, ORed or XORed together.
+ *
+ * @todo Test AND, OR and XOR of "value" condition values.
  */
 function states_exercise_multiple_conditions($form, &$form_state, $operator, $form_element) {
   // Secondary tabs might wrap to second line.
@@ -254,12 +255,12 @@
   foreach ($fields as $type => $field) {
     // Exclude multiple selects, since they don't work and would prevent
     // testing.
-    // TODO: Remove this when issue http://drupal.org/node/1149078 is fixed.
+    // @todo: Remove this when issue http://drupal.org/node/1149078 is fixed.
     if ($type == 'select_multiple') {
       continue;
     }
     // Exclude checkboxes, since they don't work and would prevent testing.
-    // TODO: file an issue :)
+    // @todo: Remove this when issue http://drupal.org/node/1032062 is fixed.
     if ($type == 'checkboxes') {
       continue;
     }
@@ -317,8 +318,10 @@
 }
 
 /**
- * Allows testing of mixed AND, OR and XOR conditions on the same dependent.
- * TODO: test what works and what doesn't when mixing states in several ways.
+ * Menu callback; allows manual testing of mixed AND, OR and XOR conditions on
+ * the same dependent.
+ *
+ * @todo Test what works and what doesn't when mixing states in several ways.
  */
 function states_exercise_multiple_conditions_mixed() {
   // Secondary tabs might wrap to second line.
@@ -357,7 +360,9 @@
 }
 
 /**
- * List of element states from drupal_process_states().
+ * Returns an array of possible form element states.
+ *
+ * @see drupal_process_states()
  */
 function states_exercise_states() {
   return array(
@@ -375,7 +380,9 @@
 }
 
 /**
- * List of conditions from drupal_process_states().
+ * Returns an array of possible states conditions.
+ *
+ * @see drupal_process_states().
  */
 function states_exercise_conditions() {
   return array(
@@ -390,10 +397,11 @@
 }
 
 /**
- * Basic form element definitions to be used as dependees and dependents.
- * The properties #relevant_states and #relevant_conditions are used
- * to exclude the elements in specific cases (for example, it doesn't make
- * sense to test if a textfield is checked when a fieldset is disabled).
+ * Returns an array of form elements to be used as dependees and dependents.
+ *
+ * The custom properties #relevant_states and #relevant_conditions are used to
+ * exclude the elements in specific cases (for example, it doesn't make sense to
+ * test if a textfield is checked when a fieldset is disabled).
  */
 function states_exercise_form_elements() {
   return array(