From 053e968f3c08cdd3f18c3193c54679f05da1a091 Mon Sep 17 00:00:00 2001
From: daniel <daniel.kinzler@wikimedia.de>
Date: Wed, 26 Aug 2015 18:17:05 +0200
Subject: [PATCH] Add comments clarifying how calling getters on ParserOutput
 affects the parser cache.

Change-Id: Ie6a4a8989df218f88cfc7c1cf1d4b68cf871abbb
---
 includes/parser/ParserOptions.php | 27 ++++++++++++++++++---------
 includes/parser/ParserOutput.php  |  2 ++
 2 files changed, 20 insertions(+), 9 deletions(-)

diff --git a/includes/parser/ParserOptions.php b/includes/parser/ParserOptions.php
index e4c867ae79..4459047a35 100644
--- 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 15321c2186..2eb1dc9f95 100644
--- 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
-- 
2.20.1