rdbms: Improve IConnectionProvider and ReadOnlyMode docs

Change-Id: Ic8af1bc3dc5a55584947c932166cc25e942b7539

2 files changed, 18 insertions, 12 deletions

diff --git a/includes/db/ConfiguredReadOnlyMode.php b/includes/db/ConfiguredReadOnlyMode.php
index 436c80116217..9c85374223dc 100644
--- a/includes/db/ConfiguredReadOnlyMode.php
+++ b/includes/db/ConfiguredReadOnlyMode.php
@@ -3,8 +3,13 @@
 namespace MediaWiki\DB;
 
 /**
- * A read-only mode service which does not depend on LoadBalancer.
- * To obtain an instance, use MediaWikiServices::getInstance()->getConfiguredReadOnlyMode().
+ * Determine whether a site is statically configured as read-only.
+ *
+ * Unlike ReadOnlyMode, this only checks site configuration.
+ * It does not confirm whether the primary database host actively accepts writes.
+ *
+ * To obtain an instance, use \MediaWiki\MediaWikiServices::getConfiguredReadOnlyMode().
+ * This service can be configured via $wgReadOnly and $wgReadOnlyFile.
  *
  * @since 1.29
  */
@@ -20,7 +25,7 @@ class ConfiguredReadOnlyMode {
 	 *   in $reasonFile instead.
 	 * @param string|null $reasonFile A file to look in for a reason, if $reason is null. If it
 	 *   exists and is non-empty, its contents are treated as the reason for read-only mode.
-	 *   Otherwise, the wiki is not read-only.
+	 *   Otherwise, the site is not read-only.
 	 */
 	public function __construct( $reason, ?string $reasonFile = null ) {
 		$this->reason = $reason;
@@ -28,7 +33,7 @@ class ConfiguredReadOnlyMode {
 	}
 
 	/**
-	 * Check whether the wiki is in read-only mode.
+	 * Check whether the site is in read-only mode.
 	 *
 	 * @return bool
 	 */
@@ -37,8 +42,6 @@ class ConfiguredReadOnlyMode {
 	}
 
 	/**
-	 * Get the value of $wgReadOnly or the contents of $wgReadOnlyFile.
-	 *
 	 * @return string|false String when in read-only mode; false otherwise
 	 */
 	public function getReason() {
diff --git a/includes/db/ReadOnlyMode.php b/includes/db/ReadOnlyMode.php
index d02f2b51492b..8305305b60c6 100644
--- a/includes/db/ReadOnlyMode.php
+++ b/includes/db/ReadOnlyMode.php
@@ -5,8 +5,9 @@ namespace MediaWiki\DB;
 use Wikimedia\Rdbms\ILoadBalancer;
 
 /**
- * A service class for fetching the wiki's current read-only mode.
- * To obtain an instance, use MediaWikiServices::getInstance()->getReadOnlyMode().
+ * Determine whether a site is currently in read-only mode.
+ *
+ * To obtain an instance, use \MediaWiki\MediaWikiServices::getReadOnlyMode().
  *
  * @since 1.29
  */
@@ -23,7 +24,7 @@ class ReadOnlyMode {
 	}
 
 	/**
-	 * Check whether the wiki is in read-only mode.
+	 * Check whether the site is in read-only mode.
 	 *
 	 * @return bool
 	 */
@@ -34,8 +35,10 @@ class ReadOnlyMode {
 	/**
 	 * Check if the site is in read-only mode and return the message if so
 	 *
-	 * This checks the configuration and registered DB load balancers for
-	 * read-only mode. This may result in DB connection being made.
+	 * This checks both statically configured read-only mode, and (cached)
+	 * whether the primary database host accepting writes.
+	 *
+	 * Calling this may result in database connection.
 	 *
 	 * @return string|false String when in read-only mode; false otherwise
 	 */
@@ -49,7 +52,7 @@ class ReadOnlyMode {
 	}
 
 	/**
-	 * Set the read-only mode, which will apply for the remainder of the
+	 * Override the read-only mode, which will apply for the remainder of the
 	 * request or until a service reset.
 	 *
 	 * @param string|false|null $msg