From 22e75a7ca7fb01fcffac196cd7bc79855707b0b7 Mon Sep 17 00:00:00 2001
From: daniel <daniel.kinzler@wikimedia.de>
Date: Mon, 2 Dec 2013 14:20:26 +0100
Subject: [PATCH] Document parser cache key control.

This documents how implementations of the Content interface
can control the parser cache key by calling ParserOutput::recordOption()

Change-Id: I9e8ad1e33e06aceea6e63c7d5575679f84ce4004
---
 includes/content/Content.php     |  4 ++++
 includes/parser/ParserCache.php  | 10 +++++++++-
 includes/parser/ParserOutput.php | 11 ++++++++---
 3 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/includes/content/Content.php b/includes/content/Content.php
index da49ced4ec..947e34819c 100644
--- a/includes/content/Content.php
+++ b/includes/content/Content.php
@@ -252,6 +252,10 @@ interface Content {
 	 * is needed, $generateHtml can be set to false; in that case,
 	 * $result->getText() may return null.
 	 *
+	 * @note To control which options are used in the cache key for the
+	 *       generated parser output, implementations of this method
+	 *       may call ParserOutput::recordOption() on the output object.
+	 *
 	 * @param $title Title The page title to use as a context for rendering
 	 * @param $revId null|int The revision being rendered (optional)
 	 * @param $options null|ParserOptions Any parser options
diff --git a/includes/parser/ParserCache.php b/includes/parser/ParserCache.php
index 7043b4a960..6ab83146d1 100644
--- a/includes/parser/ParserCache.php
+++ b/includes/parser/ParserCache.php
@@ -114,7 +114,14 @@ class ParserCache {
 	}
 
 	/**
-	 * Used to provide a unique id for the PoolCounter.
+	 * Generates a key for caching the given article considering
+	 * the given parser options.
+	 *
+	 * @note Which parser options influence the cache key
+	 * is controlled via ParserOutput::recordOption() or
+	 * ParserOptions::addExtraKey().
+	 *
+	 * @note Used by Article to provide a unique id for the PoolCounter.
 	 * It would be preferable to have this code in get()
 	 * instead of having Article looking in our internals.
 	 *
@@ -143,6 +150,7 @@ class ParserCache {
 				return false;
 			}
 
+			// $optionsKey->mUsedOptions is set by save() by calling ParserOutput::getUsedOptions()
 			$usedOptions = $optionsKey->mUsedOptions;
 			wfDebug( "Parser cache options found.\n" );
 		} else {
diff --git a/includes/parser/ParserOutput.php b/includes/parser/ParserOutput.php
index 29502270f4..57b8ebc397 100644
--- a/includes/parser/ParserOutput.php
+++ b/includes/parser/ParserOutput.php
@@ -453,10 +453,15 @@ class ParserOutput extends CacheTime {
 	}
 
 	/**
-	 * Callback passed by the Parser to the ParserOptions to keep track of which options are used.
-	 * @access private
+	 * Tags a parser option for use in the cache key for this parser output.
+	 * Registered as a watcher at ParserOptions::registerWatcher() by Parser::clearState().
+	 *
+	 * @see ParserCache::getKey
+	 * @see ParserCache::save
+	 * @see ParserOptions::addExtraKey
+	 * @see ParserOptions::optionsHash
 	 */
-	function recordOption( $option ) {
+	public function recordOption( $option ) {
 		$this->mAccessedOptions[$option] = true;
 	}
 
-- 
2.20.1