Index: modules/user/user.admin.inc
===================================================================
RCS file: /cvs/drupal/drupal/modules/user/user.admin.inc,v
retrieving revision 1.22
diff -u -p -r1.22 user.admin.inc
--- modules/user/user.admin.inc	7 May 2008 19:34:24 -0000	1.22
+++ modules/user/user.admin.inc	8 May 2008 20:58:14 -0000
@@ -630,12 +630,18 @@ function user_admin_role() {
     $form['name'] = array(
       '#type' => 'textfield',
       '#title' => t('Role name'),
-      '#default_value' => $role->name,
+      '#default_value' => check_plain($role->name),
       '#size' => 30,
       '#required' => TRUE,
       '#maxlength' => 64,
       '#description' => t('The name for this role. Example: "moderator", "editorial board", "site architect".'),
     );
+    $form['description'] = array(
+      '#type' => 'textarea',
+      '#title' => t('Description'),
+      '#default_value' => filter_xss_admin($role->description),
+      '#description' => t('A description of the role to explain what it is for. Example: "Can perform content administration tasks, but cannot ban users."'),
+    );
     $form['rid'] = array(
       '#type' => 'value',
       '#value' => $rid,
@@ -652,9 +658,13 @@ function user_admin_role() {
   else {
     $form['name'] = array(
       '#type' => 'textfield',
-      '#size' => 32,
+      '#size' => 20,
       '#maxlength' => 64,
     );
+    $form['description'] = array(
+      '#type' => 'textarea',
+      '#cols' => 32,
+    );
     $form['submit'] = array(
       '#type' => 'submit',
       '#value' => t('Add role'),
@@ -685,7 +695,7 @@ function user_admin_role_validate($form,
 
 function user_admin_role_submit($form, &$form_state) {
   if ($form_state['values']['op'] == t('Save role')) {
-    db_query("UPDATE {role} SET name = '%s' WHERE rid = %d", $form_state['values']['name'], $form_state['values']['rid']);
+    db_query("UPDATE {role} SET name = '%s', description = '%s' WHERE rid = %d", $form_state['values']['name'], $form_state['values']['description'], $form_state['values']['rid']);
     drupal_set_message(t('The role has been renamed.'));
   }
   else if ($form_state['values']['op'] == t('Delete role')) {
@@ -697,7 +707,7 @@ function user_admin_role_submit($form, &
     drupal_set_message(t('The role has been deleted.'));
   }
   else if ($form_state['values']['op'] == t('Add role')) {
-    db_query("INSERT INTO {role} (name) VALUES ('%s')", $form_state['values']['name']);
+    db_query("INSERT INTO {role} (name, description) VALUES ('%s', '%s')", $form_state['values']['name'], $form_state['values']['description']);
     drupal_set_message(t('The role has been added.'));
   }
   $form_state['redirect'] = 'admin/user/roles';
@@ -755,17 +765,17 @@ function theme_user_admin_account($form)
  * @ingroup themeable
  */
 function theme_user_admin_new_role($form) {
-  $header = array(t('Name'), array('data' => t('Operations'), 'colspan' => 2));
-  foreach (user_roles() as $rid => $name) {
+  $header = array(t('Name'), t('Description'), array('data' => t('Operations'), 'colspan' => 2));
+  foreach (user_roles() as $rid => $role) {
     $edit_permissions = l(t('edit permissions'), 'admin/user/permissions/' . $rid);
     if (!in_array($rid, array(DRUPAL_ANONYMOUS_RID, DRUPAL_AUTHENTICATED_RID))) {
-      $rows[] = array($name, l(t('edit role'), 'admin/user/roles/edit/' . $rid), $edit_permissions);
+      $rows[] = array(check_plain($role->name), filter_xss_admin($role->description), l(t('edit role'), 'admin/user/roles/edit/' . $rid), $edit_permissions);
     }
     else {
-      $rows[] = array($name, t('locked'), $edit_permissions);
+      $rows[] = array($role->name, $role->description, t('locked'), $edit_permissions);
     }
   }
-  $rows[] = array(drupal_render($form['name']), array('data' => drupal_render($form['submit']), 'colspan' => 2));
+  $rows[] = array(drupal_render($form['name']), drupal_render($form['description']), array('data' => drupal_render($form['submit'])));
 
   $output = drupal_render($form);
   $output .= theme('table', $header, $rows);
Index: modules/user/user.install
===================================================================
RCS file: /cvs/drupal/drupal/modules/user/user.install,v
retrieving revision 1.12
diff -u -p -r1.12 user.install
--- modules/user/user.install	7 May 2008 19:34:24 -0000	1.12
+++ modules/user/user.install	8 May 2008 20:58:14 -0000
@@ -80,6 +80,12 @@ function user_schema() {
         'default' => '',
         'description' => t('Unique role name.'),
       ),
+      'description' => array(
+        'type' => 'varchar',
+        'length' => 255,
+        'default' => '',
+        'description' => t("Description of the role. Used for documenting roles' usage."),
+      ),
     ),
     'unique keys' => array(
       'name' => array('name'),
@@ -281,7 +287,6 @@ function user_update_7000(&$sandbox) {
  *
  * These fields were previously used to store per-user comment settings.
  */
-
 function user_update_7001() {
   $ret = array();
   db_drop_field($ret, 'users', 'threshold');
@@ -292,6 +297,28 @@ function user_update_7001() {
 }
 
 /**
+ * Add descriptions to roles.
+ */
+function user_update_7002() {
+  $ret = array();
+
+  // Add description column.
+  $field = array(
+    'description' => t("Description of the role. Used for documenting roles' usage."),
+    'type' => 'varchar',
+    'length' => 255,
+    'default' => '',
+  );
+  db_add_field($ret, 'role', 'description', $field);
+
+  // Populate anonymous and autheticated role descriptions.
+  $ret[] = update_sql("UPDATE {role} SET description = 'Visitors to the website who have not yet logged in. Users have limited permissions on the site.' WHERE rid = " . DRUPAL_ANONYMOUS_RID);
+  $ret[] = update_sql("UPDATE {role} SET description = 'Any logged-in user. Other roles receive the permissions of this role, as well as any other roles to which they are assigned.' WHERE rid = " . DRUPAL_AUTHENTICATED_RID);
+
+  return $ret;
+}
+
+/**
  * @} End of "defgroup user-updates-6.x-to-7.x"
  * The next series of updates should start at 8000.
  */
Index: modules/user/user.module
===================================================================
RCS file: /cvs/drupal/drupal/modules/user/user.module,v
retrieving revision 1.907
diff -u -p -r1.907 user.module
--- modules/user/user.module	7 May 2008 19:34:24 -0000	1.907
+++ modules/user/user.module	8 May 2008 20:58:15 -0000
@@ -1654,14 +1654,16 @@ function user_roles($membersonly = FALSE
       // We only translate the built in role names
       case DRUPAL_ANONYMOUS_RID:
         if (!$membersonly) {
-          $roles[$role->rid] = t($role->name);
+          $role->name = t($role->name);
+          $roles[$role->rid] = $role;
         }
         break;
       case DRUPAL_AUTHENTICATED_RID:
-        $roles[$role->rid] = t($role->name);
+        $role->name = t($role->name);
+        $roles[$role->rid] = $role;
         break;
       default:
-        $roles[$role->rid] = $role->name;
+        $roles[$role->rid] = $role;
     }
   }