Explaining why user groups are sometimes returned by getRestrictions

Title::getRestrictions is assumed to return user rights, but in most
real contexts it actually returns user groups. This is super
confusing and has caused serious permission bugs. Adding an
explanation to the function comments.

Change-Id: I58013ba5e553d1feecacf6bfef066e1569fcc236

diff --git a/includes/Title.php b/includes/Title.php
index cfdba5d..4b60bcb 100644 (file)
--- a/includes/Title.php
+++ b/includes/Title.php
@@ -2812,8 +2812,10 @@ class Title {
         * Accessor/initialisation for mRestrictions
         *
         * @param string $action Action that permission needs to be checked for
-        * @return array Restriction levels needed to take the action. All levels
-        *     are required.
+        * @return array Restriction levels needed to take the action. All levels are
+        *     required. Note that restriction levels are normally user rights, but 'sysop'
+        *     and 'autoconfirmed' are also allowed for backwards compatibility. These should
+        *     be mapped to 'editprotected' and 'editsemiprotected' respectively.
         */
        public function getRestrictions( $action ) {
                if ( !$this->mRestrictionsLoaded ) {