diff --git a/core/includes/bootstrap.inc b/core/includes/bootstrap.inc
index 07c9d67..d49dd43 100644
--- a/core/includes/bootstrap.inc
+++ b/core/includes/bootstrap.inc
@@ -1764,22 +1764,40 @@ function watchdog($type, $message, $variables = array(), $severity = WATCHDOG_NO
 }
 
 /**
- * Sets a message which reflects the status of the performed operation.
+ * Sets a message to display to the user.
  *
- * If the function is called with no arguments, this function returns all set
- * messages without clearing them.
+ * Messages are stored in a session variable and displayed in the "System help"
+ * block.
  *
- * @param $message
- *   The message to be displayed to the user. For consistency with other
- *   messages, it should begin with a capital letter and end with a period.
- * @param $type
- *   The type of the message. One of the following values are possible:
+ * Example usage:
+ * @code
+ * drupal_set_message(t('An error occurred and processing did not complete.'), 'error');
+ * @endcode
+ *
+ * If the function is called without arguments, it returns all set messages
+ * without clearing them.
+ *
+ * @param string $message
+ *   The translated message to be displayed to the user. For consistency with
+ *   other messages, it should begin with a capital letter and end with a
+ *   period.
+ * @param string $type
+ *   The message's type. Defaults to 'status'. These values are supported:
  *   - 'status'
  *   - 'warning'
  *   - 'error'
- * @param $repeat
+ * @param bool $repeat
  *   If this is FALSE and the message is already set, then the message won't
- *   be repeated.
+ *   be repeated. Defaults to TRUE.
+ *
+ * @return array|null
+ *   A multidimensional array with keys corresponding to the set message types.
+ *   The indexed array values of each contain the set messages for that type.
+ *   Or, if there are no messages set, the function returns NULL.
+ *
+ * @see drupal_get_messages()
+ * @see theme_status_messages()
+ *
  */
 function drupal_set_message($message = NULL, $type = 'status', $repeat = TRUE) {
   if ($message) {