Thijs/wiki.techinc.nl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Clarify documentation of Maintenance::runChild

Browse source 
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
This commit is contained in:
Dreamy Jazz 2024-09-02 15:47:48 +01:00
parent e80ea2602e
commit af4117bbdd
1 changed files with 24 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
maintenance/includes/Maintenance.php
View file

@ -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
* @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
* @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 ) {
public function createChild( string $maintClass, ?string $classFile = null ): Maintenance {
// Make sure the class is loaded first
if ( !class_exists( $maintClass ) ) {
if ( $classFile ) {