Document cross-wiki cache sharing logic.

This makes explicit the fact that some classes can use the local wiki's default
WANObjectCache instance while still sharing cache entries between wikis.

Bug: T198704
Change-Id: Ic29f79e4b4bd6bdaa844049962a163e72a59c45a

diff --git a/includes/Storage/NameTableStore.php b/includes/Storage/NameTableStore.php
index 23b2902..52e8f5b 100644 (file)
--- a/includes/Storage/NameTableStore.php
+++ b/includes/Storage/NameTableStore.php
@@ -66,7 +66,12 @@ class NameTableStore {
 
        /**
         * @param ILoadBalancer $dbLoadBalancer A load balancer for acquiring database connections
-        * @param WANObjectCache $cache A cache manager for caching data
+        * @param WANObjectCache $cache A cache manager for caching data. This can be the local
+        *        wiki's default instance even if $wikiId refers to a different wiki, since
+        *        makeGlobalKey() is used to constructed a key that allows cached names from
+        *        the same database to be re-used between wikis. For example, enwiki and frwiki will
+        *        use the same cache keys for names from the wikidatawiki database, regardless
+        *        of the cache's default key space.
         * @param LoggerInterface $logger
         * @param string $table
         * @param string $idField

diff --git a/includes/Storage/RevisionStore.php b/includes/Storage/RevisionStore.php
index 0796d62..65c0361 100644 (file)
--- a/includes/Storage/RevisionStore.php
+++ b/includes/Storage/RevisionStore.php
@@ -130,7 +130,12 @@ class RevisionStore
         *
         * @param ILoadBalancer $loadBalancer
         * @param SqlBlobStore $blobStore
-        * @param WANObjectCache $cache
+        * @param WANObjectCache $cache A cache for caching revision rows. This can be the local
+        *        wiki's default instance even if $wikiId refers to a different wiki, since
+        *        makeGlobalKey() is used to constructed a key that allows cached revision rows from
+        *        the same database to be re-used between wikis. For example, enwiki and frwiki will
+        *        use the same cache keys for revision rows from the wikidatawiki database, regardless
+        *        of the cache's default key space.
         * @param CommentStore $commentStore
         * @param NameTableStore $contentModelStore
         * @param NameTableStore $slotRoleStore

diff --git a/includes/Storage/SqlBlobStore.php b/includes/Storage/SqlBlobStore.php
index 48ffe2c..d7216c5 100644 (file)
--- a/includes/Storage/SqlBlobStore.php
+++ b/includes/Storage/SqlBlobStore.php
@@ -94,7 +94,12 @@ class SqlBlobStore implements IDBAccessObject, BlobStore {
 
        /**
         * @param LoadBalancer $dbLoadBalancer A load balancer for acquiring database connections
-        * @param WANObjectCache $cache A cache manager for caching blobs
+        * @param WANObjectCache $cache A cache manager for caching blobs. This can be the local
+        *        wiki's default instance even if $wikiId refers to a different wiki, since
+        *        makeGlobalKey() is used to constructed a key that allows cached blobs from the
+        *        same database to be re-used between wikis. For example, enwiki and frwiki will
+        *        use the same cache keys for blobs from the wikidatawiki database, regardless of
+        *        the cache's default key space.
         * @param bool|string $wikiId The ID of the target wiki database. Use false for the local wiki.
         */
        public function __construct(