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

diff --git a/includes/content/Content.php b/includes/content/Content.php
index da49ced..947e348 100644 (file)
--- 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 7043b4a..6ab8314 100644 (file)
--- 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 2950227..57b8ebc 100644 (file)
--- 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;
        }