From fa0ad435f50f3c4761cbe4c3520531e019b2621b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Petr=20S=CC=8Ckoda?= <commits@skodak.org>
Date: Sun, 7 Apr 2013 17:39:29 +0200
Subject: [PATCH] MDL-39004 improve role docs

---
 lib/accesslib.php | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/lib/accesslib.php b/lib/accesslib.php
index 7d179745e57..d26e7925743 100644
--- a/lib/accesslib.php
+++ b/lib/accesslib.php
@@ -2990,6 +2990,9 @@ function user_can_assign(context $context, $targetroleid) {
 /**
  * Returns all site roles in correct sort order.
  *
+ * Note: this method does not localise role names or descriptions,
+ *       use role_get_names() if you need role names.
+ *
  * @param context $context optional context for course role name aliases
  * @return array of role records with optional coursealias property
  */
@@ -4249,7 +4252,7 @@ function user_has_role_assignment($userid, $roleid, $contextid = 0) {
 }
 
 /**
- * Get role name or alias if exists and format the text.
+ * Get localised role name or alias if exists and format the text.
  *
  * @param stdClass $role role object
  *      - optional 'coursealias' property should be included for performance reasons if course context used
@@ -4363,6 +4366,9 @@ function role_get_description(stdClass $role) {
 /**
  * Get all the localised role names for a context.
  *
+ * In new installs default roles have empty names, this function
+ * add localised role names using current language pack.
+ *
  * @param context $context the context, null means system context
  * @param array of role objects with a ->localname field containing the context-specific role name.
  * @param int $rolenamedisplay
@@ -4374,7 +4380,7 @@ function role_get_names(context $context = null, $rolenamedisplay = ROLENAME_ALI
 }
 
 /**
- * Prepare list of roles for display, apply aliases and format text
+ * Prepare list of roles for display, apply aliases and localise default role names.
  *
  * @param array $roleoptions array roleid => roleobject (with optional coursealias), strings are accepted for backwards compatibility only
  * @param context $context the context, null means system context