Clarify documentation of Maintenance::runChild

Why:
* The Maintenance::runChild method is named in a way which makes
  it easy to assume that calling the method will directly
  execute the passed maintenance script
** The documentation does not help either, with it also implying
   that the script will be run once the method is called.
* Instead callers are expected to run the maintenance script by
  calling ::execute on the returned object
* The method name should be changed to make this clearer and
  the documentation improved.

What:
* Rename Maintenance::runChild to ::createChild, which makes it
  clearer that the maintenance script has not been run
** Leave ::runChild as an alias to ::createChild, as ::runChild
   was marked as stable to override.
* Improve the documentation for Maintenance::createChild to
  make it clear that callers need to call ::execute on the returned
  Maintenance object.

Bug: T371789
Change-Id: I7d0914ebaaa3ff5da05bccebb57cc76aad120dd5

1 files changed, 24 insertions, 4 deletions

diff --git a/maintenance/includes/Maintenance.php b/maintenance/includes/Maintenance.php
index 6b15a8f1a693..d2f54cb91e0a 100644
--- a/maintenance/includes/Maintenance.php
+++ b/maintenance/includes/Maintenance.php
@@ -724,14 +724,34 @@ abstract class Maintenance {
 	}
 
 	/**
-	 * Run a child maintenance script. Pass all of the current arguments
-	 * to it.
+	 * Returns an instance of the given maintenance script, with all of the current arguments
+	 * passed to it.
+	 *
+	 * Callers are expected to run the returned maintenance script instance by calling {@link Maintenance::execute}
+	 *
+	 * @deprecated Since 1.43. Use {@link Maintenance::createChild} instead. This method is an alias to that method.
 	 * @param string $maintClass A name of a child maintenance class
 	 * @param string|null $classFile Full path of where the child is
-	 * @stable to override
-	 * @return Maintenance
+	 * @return Maintenance The created instance, which the caller is expected to run by calling
+	 *   {@link Maintenance::execute} on the returned object.
 	 */
 	public function runChild( $maintClass, $classFile = null ) {
+		return self::createChild( $maintClass, $classFile );
+	}
+
+	/**
+	 * Returns an instance of the given maintenance script, with all of the current arguments
+	 * passed to it.
+	 *
+	 * Callers are expected to run the returned maintenance script instance by calling {@link Maintenance::execute}
+	 *
+	 * @param string $maintClass A name of a child maintenance class
+	 * @param string|null $classFile Full path of where the child is
+	 * @stable to override
+	 * @return Maintenance The created instance, which the caller is expected to run by calling
+	 *   {@link Maintenance::execute} on the returned object.
+	 */
+	public function createChild( string $maintClass, ?string $classFile = null ): Maintenance {
 		// Make sure the class is loaded first
 		if ( !class_exists( $maintClass ) ) {
 			if ( $classFile ) {