Index: modules/user/user.install
===================================================================
RCS file: /cvs/drupal/drupal/modules/user/user.install,v
retrieving revision 1.17
diff -u -r1.17 user.install
--- modules/user/user.install	20 Jan 2009 03:10:00 -0000	1.17
+++ modules/user/user.install	9 Mar 2009 02:43:00 -0000
@@ -80,6 +80,12 @@
         'default' => '',
         'description' => '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'),
@@ -464,6 +470,28 @@
 }
 
 /**
+ * Add descriptions to roles.
+ */
+function user_update_7005() {
+  $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.963
diff -u -r1.963 user.module
--- modules/user/user.module	9 Feb 2009 07:36:15 -0000	1.963
+++ modules/user/user.module	9 Mar 2009 02:43:01 -0000
@@ -1242,10 +1242,31 @@
     'page arguments' => array('user_admin_new_role'),
     'access arguments' => array('administer permissions'),
   );
-  $items['admin/user/roles/edit'] = array(
-    'title' => 'Edit role',
+  $items['admin/user/roles/list'] = array(
+    'title' => 'List',
+    'type' => MENU_DEFAULT_LOCAL_TASK,
+    'weight' => -10,
+  );
+  $items['admin/user/roles/add'] = array(
+    'title' => 'Add role',
+    'description' => 'List, edit, or add user roles.',
+    //'page callback' => 'drupal_get_form',
     'page arguments' => array('user_admin_role'),
     'access arguments' => array('administer permissions'),
+    'type' => MENU_LOCAL_TASK,
+  );
+  $items['admin/user/roles/edit/%'] = array(
+    'title' => 'Edit role',
+    'page arguments' => array('user_admin_role', 4),
+    'access arguments' => array('administer permissions'),
+    'type' => MENU_CALLBACK,
+  );
+
+    $items['admin/user/roles/delete/%'] = array(
+    'title' => 'Delete role',
+    //'page callback' => 'drupal_get_form',
+    'page arguments' => array('user_admin_role_delete', 4),
+    'access arguments' => array('administer permissions'),
     'type' => MENU_CALLBACK,
   );
 
@@ -2021,14 +2042,16 @@
       // 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;
     }
   }
 
@@ -2256,11 +2279,7 @@
     case 'admin/user/permissions':
       return '<p>' . t('Permissions let you control what users can do on your site. Each user role (defined on the <a href="@role">user roles page</a>) has its own set of permissions. For example, you could give users classified as "Administrators" permission to "administer nodes" but deny this power to ordinary, "authenticated" users. You can use permissions to reveal new features to privileged users (those with subscriptions, for example). Permissions also allow trusted users to share the administrative burden of running a busy site.', array('@role' => url('admin/user/roles'))) . '</p>';
     case 'admin/user/roles':
-      return t('<p>Roles allow you to fine tune the security and administration of Drupal. A role defines a group of users that have certain privileges as defined in <a href="@permissions">user permissions</a>. Examples of roles include: anonymous user, authenticated user, moderator, administrator and so on. In this area you will define the <em>role names</em> of the various roles. To delete a role choose "edit".</p><p>By default, Drupal comes with two user roles:</p>
-      <ul>
-      <li>Anonymous user: this role is used for users that don\'t have a user account or that are not authenticated.</li>
-      <li>Authenticated user: this role is automatically granted to all logged in users.</li>
-      </ul>', array('@permissions' => url('admin/user/permissions')));
+      return t('<p>Roles allow you to fine tune the security and administration of Drupal. A role defines a group of users that have certain privileges as defined in <a href="@permissions">user permissions</a>. Examples of roles include: anonymous user, authenticated user, moderator, administrator and so on. In this area you will define the <em>role names</em> of the various roles.</p><p>Authenticated user and Anonymous user are two default roles that cannot be deleted.</p>', array('@permissions' => url('admin/user/permissions')));
     case 'admin/user/search':
       return '<p>' . t('Enter a simple pattern ("*" may be used as a wildcard match) to search for a username or e-mail address. For example, one may search for "br" and Drupal might return "brian", "brad", and "brenda@example.com".') . '</p>';
   }
Index: modules/user/user.admin.inc
===================================================================
RCS file: /cvs/drupal/drupal/modules/user/user.admin.inc,v
retrieving revision 1.37
diff -u -r1.37 user.admin.inc
--- modules/user/user.admin.inc	3 Feb 2009 18:55:32 -0000	1.37
+++ modules/user/user.admin.inc	9 Mar 2009 02:43:00 -0000
@@ -663,91 +663,98 @@
  * @see user_admin_role_submit()
  * @see theme_user_admin_new_role()
  */
-function user_admin_role() {
-  $rid = arg(4);
+function user_admin_role($form_id, $rid = NULL) {
   if ($rid) {
-    if ($rid == DRUPAL_ANONYMOUS_RID || $rid == DRUPAL_AUTHENTICATED_RID) {
+    $role = db_fetch_object(db_query('SELECT rid, name, description FROM {role} WHERE rid = %d', $rid));
+    //return to roles list if invalid rid
+    if(empty($role)) {
       drupal_goto('admin/user/roles');
     }
-    // Display the edit role form.
-    $role = db_fetch_object(db_query('SELECT * FROM {role} WHERE rid = %d', $rid));
-    $form['name'] = array(
-      '#type' => 'textfield',
-      '#title' => t('Role name'),
-      '#default_value' => $role->name,
-      '#size' => 30,
-      '#required' => TRUE,
-      '#maxlength' => 64,
-      '#description' => t('The name for this role. Example: "moderator", "editorial board", "site architect".'),
-    );
-    $form['rid'] = array(
-      '#type' => 'value',
-      '#value' => $rid,
-    );
-    $form['submit'] = array(
-      '#type' => 'submit',
-      '#value' => t('Save role'),
-    );
-    $form['delete'] = array(
-      '#type' => 'submit',
-      '#value' => t('Delete role'),
-    );
-  }
-  else {
-    $form['name'] = array(
-      '#type' => 'textfield',
-      '#size' => 32,
-      '#maxlength' => 64,
-    );
-    $form['submit'] = array(
-      '#type' => 'submit',
-      '#value' => t('Add role'),
-    );
-    $form['#submit'][] = 'user_admin_role_submit';
-    $form['#validate'][] = 'user_admin_role_validate';
   }
+  $form['name'] = array(
+    '#type' => 'textfield',
+    '#title' => t('Role name'),
+    '#default_value' => isset($role->name) ? check_plain($role->name) : NULL,
+    '#size' => 30,
+    '#required' => TRUE,
+    '#maxlength' => 64,
+    '#description' => t('The name for this role. Example: "moderator", "editorial board", "site architect".'),
+    '#disabled' => ($rid == DRUPAL_ANONYMOUS_RID || $rid == DRUPAL_AUTHENTICATED_RID),
+  );
+  $form['description'] = array(
+    '#type' => 'textarea',
+    '#title' => t('Description'),
+    '#default_value' => isset($role->description) ? filter_xss_admin($role->description) : NULL,
+    '#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,
+  );
+  $form['submit'] = array(
+    '#type' => 'submit',
+    '#value' => t('Save role'),
+  );
+  $form['#submit'][] = 'user_admin_role_submit';
+  $form['#validate'][] = 'user_admin_role_validate';
   return $form;
 }
 
 function user_admin_role_validate($form, &$form_state) {
-  if ($form_state['values']['name']) {
-    if ($form_state['values']['op'] == t('Save role')) {
-      if (db_result(db_query("SELECT COUNT(*) FROM {role} WHERE name = '%s' AND rid != %d", $form_state['values']['name'], $form_state['values']['rid']))) {
-        form_set_error('name', t('The role name %name already exists. Please choose another role name.', array('%name' => $form_state['values']['name'])));
-      }
-    }
-    elseif ($form_state['values']['op'] == t('Add role')) {
-      if (db_result(db_query("SELECT COUNT(*) FROM {role} WHERE name = '%s'", $form_state['values']['name']))) {
-        form_set_error('name', t('The role name %name already exists. Please choose another role name.', array('%name' => $form_state['values']['name'])));
-      }
-    }
-  }
-  else {
-    form_set_error('name', t('You must specify a valid role name.'));
+  $role_exists = db_result(db_query("SELECT rid FROM {role} WHERE name = '%s' AND rid != %d", $form_state['values']['name'], $form_state['values']['rid']));
+  if ($role_exists) {
+      form_set_error('name', t('The role name %name already exists. Please choose another role name.', array('%name' => $form_state['values']['name'])));
   }
 }
 
 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']);
+  if ($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.'));
   }
-  elseif ($form_state['values']['op'] == t('Delete role')) {
-    db_query('DELETE FROM {role} WHERE rid = %d', $form_state['values']['rid']);
-    db_query('DELETE FROM {role_permission} WHERE rid = %d', $form_state['values']['rid']);
-    // Update the users who have this role set:
-    db_query('DELETE FROM {users_roles} WHERE rid = %d', $form_state['values']['rid']);
-
-    drupal_set_message(t('The role has been deleted.'));
-  }
-  elseif ($form_state['values']['op'] == t('Add role')) {
-    db_query("INSERT INTO {role} (name) VALUES ('%s')", $form_state['values']['name']);
+  else {
+    db_query("INSERT INTO {role} (name, description) VALUES ('%s', '%s')", array($form_state['values']['name'], $form_state['values']['description']));
     drupal_set_message(t('The role has been added.'));
   }
   $form_state['redirect'] = 'admin/user/roles';
   return;
 }
 
+function user_admin_role_delete($form_id, $rid) {
+  if ($rid == DRUPAL_ANONYMOUS_RID || $rid == DRUPAL_AUTHENTICATED_RID) {
+    drupal_goto('admin/user/roles');
+  }
+  $form = array();
+  $role = db_fetch_object(db_query('SELECT * FROM {role} WHERE rid = %d', $rid));
+  $form['rid'] = array(
+     '#type' => 'value',
+     '#value' => $rid,
+  );
+  $form = confirm_form($form,
+    t('Are you sure you want to delete the %title role?', array('%title' => $role->name)),
+    isset($_GET['destination']) ? $_GET['destination'] : 'admin/user/roles',
+    t('This action cannot be undone.'),
+    t('Delete role'),
+    t('Cancel')
+  );
+  return $form;
+}
+
+function user_admin_role_delete_validate($form, &$form_state) {
+  if ($rid == DRUPAL_ANONYMOUS_RID || $rid == DRUPAL_AUTHENTICATED_RID) {
+    drupal_goto('admin/user/roles');
+  }
+}
+
+function user_admin_role_delete_submit($form, &$form_state) {
+  db_query('DELETE FROM {role} WHERE rid = %d', $form_state['values']['rid']);
+  db_query('DELETE FROM {role_permission} WHERE rid = %d', $form_state['values']['rid']);
+  // Update the users who have this role set:
+  db_query('DELETE FROM {users_roles} WHERE rid = %d', $form_state['values']['rid']);
+  drupal_set_message(t('The role has been deleted.'));
+  $form_state['redirect'] = 'admin/user/roles';
+}
+
 /**
  * Theme user administration overview.
  *
@@ -799,20 +806,17 @@
  * @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) {
-    $edit_permissions = l(t('edit permissions'), 'admin/user/permissions/' . $rid);
+  $header = array(t('Name'), t('Description'), array('data' => t('Operations'), 'colspan' => 3));
+  foreach (user_roles() as $rid => $role) {
+    $edit_permissions = l(t('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'), 'admin/user/roles/edit/' . $rid), l(t('delete'), 'admin/user/roles/delete/' . $rid), $edit_permissions);
     }
     else {
-      $rows[] = array($name, t('locked'), $edit_permissions);
+      $rows[] = array($role->name, $role->description, l(t('edit'), 'admin/user/roles/edit/'. $rid), t('required'), $edit_permissions);
     }
   }
-  $rows[] = array(drupal_render($form['name']), array('data' => drupal_render($form['submit']), 'colspan' => 2));
-
-  $output = drupal_render_children($form);
-  $output .= theme('table', $header, $rows);
+  $output = theme('table', $header, $rows);
 
   return $output;
 }