Merge "[FileBackend] Documentation tweaks."

2 files changed, 15 insertions, 8 deletions

diff --git a/includes/filebackend/FileBackend.php b/includes/filebackend/FileBackend.php
index a3e1de3019f7..c282a075a86f 100644
--- a/includes/filebackend/FileBackend.php
+++ b/includes/filebackend/FileBackend.php
@@ -37,14 +37,18 @@
  * Outside callers can assume that all backends will have these functions.
  *
  * All "storage paths" are of the format "mwstore://<backend>/<container>/<path>".
- * The "<path>" portion is a relative path that uses UNIX file system (FS)
- * notation, though any particular backend may not actually be using a local
- * filesystem. Therefore, the relative paths are only virtual.
+ * The "backend" portion is unique name for MediaWiki to refer to a backend, while
+ * the "container" portion is a top-level directory of the backend. The "path" portion
+ * is a relative path that uses UNIX file system (FS) notation, though any particular
+ * backend may not actually be using a local filesystem. Therefore, the relative paths
+ * are only virtual.
  *
  * Backend contents are stored under wiki-specific container names by default.
- * For legacy reasons, this has no effect for the FS backend class, and per-wiki
- * segregation must be done by setting the container paths appropriately.
+ * Global (qualified) backends are achieved by configuring the "wiki ID" to a constant.
+ * For legacy reasons, the FSFileBackend class allows manually setting the paths of
+ * containers to ones that do not respect the "wiki ID".
  *
+ * In key/value stores, the container is the only hierarchy (the rest is emulated).
  * FS-based backends are somewhat more restrictive due to the existence of real
  * directory files; a regular file cannot have the same name as a directory. Other
  * backends with virtual directories may not have this limitation. Callers should
@@ -75,10 +79,13 @@ abstract class FileBackend {
 	 * $config includes:
 	 *   - name        : The unique name of this backend.
 	 *                   This should consist of alphanumberic, '-', and '_' characters.
-	 *                   This name should not be changed after use.
-	 *   - wikiId      : Prefix to container names that is unique to this wiki.
+	 *                   This name should not be changed after use (e.g. with journaling).
+	 *                   Note that the name is *not* used in actual container names.
+	 *   - wikiId      : Prefix to container names that is unique to this backend.
 	 *                   If not provided, this defaults to the current wiki ID.
 	 *                   It should only consist of alphanumberic, '-', and '_' characters.
+	 *                   This ID is what avoids collisions if multiple logical backends
+	 *                   use the same storage system, so this should be set carefully.
 	 *   - lockManager : Registered name of a file lock manager to use.
 	 *   - fileJournal : File journal configuration; see FileJournal::factory().
 	 *                   Journals simply log changes to files stored in the backend.
diff --git a/includes/filebackend/FileBackendMultiWrite.php b/includes/filebackend/FileBackendMultiWrite.php
index a443a3aadd92..a5f507397db8 100644
--- a/includes/filebackend/FileBackendMultiWrite.php
+++ b/includes/filebackend/FileBackendMultiWrite.php
@@ -62,7 +62,7 @@ class FileBackendMultiWrite extends FileBackend {
 	 * Additional $config params include:
 	 *   - backends       : Array of backend config and multi-backend settings.
 	 *                      Each value is the config used in the constructor of a
-	 *                          FileBackendStore class, but with these additional settings:
+	 *                      FileBackendStore class, but with these additional settings:
 	 *                        - class         : The name of the backend class
 	 *                        - isMultiMaster : This must be set for one backend.
 	 *                        - template:     : If given a backend name, this will use