Add comments clarifying how calling getters on ParserOutput affects the parser cache.

Change-Id: Ie6a4a8989df218f88cfc7c1cf1d4b68cf871abbb

diff --git a/includes/parser/ParserOptions.php b/includes/parser/ParserOptions.php
index e4c867a..4459047 100644 (file)
--- a/includes/parser/ParserOptions.php
+++ b/includes/parser/ParserOptions.php
@@ -372,18 +372,17 @@ class ParserOptions {
        }
 
        /**
-        * Get the user language used by the parser for this page and record the
-        * userlang parser option, which splits parser cache.
+        * Get the user language used by the parser for this page and split the parser cache.
         *
-        * You shouldn't use this. Really. $parser->getFunctionLang() is all you need.
+        * @warning: Calling this causes the parser cache to be fragmented by user language!
+        * To avoid cache fragmentation, output should not depend on the user language.
+        * Use Parser::getFunctionLang() or Parser::getTargetLanguage() instead!
         *
-        * To avoid side-effects where the page will be rendered based on the language
-        * 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.
+        * @note This function will trigger a cache fragmentation by recording the
+        * 'userlang' option, see optionUsed(). This is done to avoid cache pollution
+        * when the page is rendered based on the language of the user.
         *
+        * @note When saving, this will return the default language instead of the user's.
         * {{int: }} uses this which used to produce inconsistent link tables (bug 14404).
         *
         * @return Language
@@ -397,6 +396,12 @@ class ParserOptions {
        /**
         * Same as getUserLangObj() but returns a string instead.
         *
+        * @warning: Calling this causes the parser cache to be fragmented by user language!
+        * To avoid cache fragmentation, output should not depend on the user language.
+        * Use Parser::getFunctionLang() or Parser::getTargetLanguage() instead!
+        *
+        * @see getUserLangObj()
+        *
         * @return string Language code
         * @since 1.17
         */
@@ -702,6 +707,10 @@ class ParserOptions {
 
        /**
         * Called when an option is accessed.
+        * Calls the watcher that was set using registerWatcher().
+        * Typically, the watcher callback is ParserOutput::registerOption().
+        * The information registered that way will be used by ParserCache::save().
+        *
         * @param string $optionName Name of the option
         */
        public function optionUsed( $optionName ) {

diff --git a/includes/parser/ParserOutput.php b/includes/parser/ParserOutput.php
index 15321c2..2eb1dc9 100644 (file)
--- a/includes/parser/ParserOutput.php
+++ b/includes/parser/ParserOutput.php
@@ -686,6 +686,8 @@ class ParserOutput extends CacheTime {
        /**
         * Tags a parser option for use in the cache key for this parser output.
         * Registered as a watcher at ParserOptions::registerWatcher() by Parser::clearState().
+        * The information gathered here is available via getUsedOptions(),
+        * and is used by ParserCache::save().
         *
         * @see ParserCache::getKey
         * @see ParserCache::save