rdbms: add some more comments to DatabaseDomain

Change-Id: Iee407028a2f3c7eb6497a73d57c7baa093246217

diff --git a/includes/libs/rdbms/database/domain/DatabaseDomain.php b/includes/libs/rdbms/database/domain/DatabaseDomain.php
index 5698cf8..3ceb339 100644 (file)
--- a/includes/libs/rdbms/database/domain/DatabaseDomain.php
+++ b/includes/libs/rdbms/database/domain/DatabaseDomain.php
@@ -23,7 +23,19 @@ namespace Wikimedia\Rdbms;
 use InvalidArgumentException;
 
 /**
- * Class to handle database/prefix specification for IDatabase domains
+ * Class to handle database/schema/prefix specifications for IDatabase
+ *
+ * The components of a database domain are defined as follows:
+ *   - database: name of a server-side collection of schemas that is client-selectable
+ *   - schema: name of a server-side collection of tables within the given database
+ *   - prefix: table name prefix of an application-defined table collection
+ *
+ * If an RDBMS does not support server-side collections of table collections (schemas) then
+ * the schema component should be null and the "database" component treated as a collection
+ * of exactly one table collection (the implied schema for that "database").
+ *
+ * The above criteria should determine how components should map to RDBMS specific keywords
+ * rather than "database"/"schema" always mapping to "DATABASE"/"SCHEMA" as used by the RDBMS.
  */
 class DatabaseDomain {
        /** @var string|null */