Add comments for ParserOptions::getUserLang regarding cache split

Add details in comments for ParserOptions::getUserLang, more
explicitly warning about cache fragmentation and mention that
in some cases (e.g. multilingual wiki) this might be desired.

Change-Id: I3fe0799ade488eca32d8c89150179710309650c3

diff --git a/includes/parser/ParserOptions.php b/includes/parser/ParserOptions.php
index 100656d..ed0d74a 100644 (file)
--- a/includes/parser/ParserOptions.php
+++ b/includes/parser/ParserOptions.php
@@ -372,13 +372,15 @@ class ParserOptions {
        }
 
        /**
-        * Get the user language used by the parser for this page.
+        * Get the user language used by the parser for this page and record the
+        * userlang parser option, which splits parser cache.
         *
         * You shouldn't use this. Really. $parser->getFunctionLang() is all you need.
         *
         * To avoid side-effects where the page will be rendered based on the language
-        * of the user who last saved, this function will triger a cache fragmentation.
-        * Usage of this method is discouraged for that reason.
+        * of the user who last saved, this function will trigger a cache fragmentation.
+        * For that reason, usage of this method is discouraged unless it is desired to
+        * split caches based on user language, such as for multilingual content.
         *
         * When saving, this will return the default language instead of the user's.
         *