From 9eee3153aec291cd89b30a06480688da455dcf89 Mon Sep 17 00:00:00 2001
From: Alexandre Emsenhuber <ialex.wiki@gmail.com>
Date: Sat, 16 Jun 2012 22:35:13 +0200
Subject: [PATCH] Improve documentation of maintenance scripts.

Change-Id: I328a3d42a09f2b082ebc153c2f399793e23942d7
---
 maintenance/attachLatest.php            |  9 +++++++--
 maintenance/changePassword.php          |  5 +++++
 maintenance/checkAutoLoader.php         |  5 +++++
 maintenance/checkBadRedirects.php       |  8 ++++++--
 maintenance/checkImages.php             |  7 ++++++-
 maintenance/checkSyntax.php             |  5 +++++
 maintenance/checkUsernames.php          | 12 +++++++++---
 maintenance/convertLinks.php            | 13 ++++++++++---
 maintenance/convertUserOptions.php      |  9 ++++++++-
 maintenance/copyFileBackend.php         | 18 ++++++++++++------
 maintenance/createAndPromote.php        |  9 +++++++--
 maintenance/deleteArchivedFiles.inc     |  8 +++++++-
 maintenance/deleteArchivedFiles.php     | 10 ++++++++--
 maintenance/deleteArchivedRevisions.php | 11 +++++++++--
 14 files changed, 104 insertions(+), 25 deletions(-)

diff --git a/maintenance/attachLatest.php b/maintenance/attachLatest.php
index 6e09671a73..78cae8cfb3 100644
--- a/maintenance/attachLatest.php
+++ b/maintenance/attachLatest.php
@@ -1,7 +1,6 @@
 <?php
 /**
- * quick hackjob to fix damages imports on wikisource
- * page records have page_latest wrong
+ * Corrects wrong values in the `page_latest` field in the database.
  *
  * Copyright © 2005 Brion Vibber <brion@pobox.com>
  * http://www.mediawiki.org/
@@ -27,6 +26,12 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script to correct wrong values in the `page_latest` field
+ * in the database.
+ *
+ * @ingroup Maintenance
+ */
 class AttachLatest extends Maintenance {
 
 	public function __construct() {
diff --git a/maintenance/changePassword.php b/maintenance/changePassword.php
index cfcac40670..e4063f9c9c 100644
--- a/maintenance/changePassword.php
+++ b/maintenance/changePassword.php
@@ -26,6 +26,11 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script to change the password of a given user.
+ *
+ * @ingroup Maintenance
+ */
 class ChangePassword extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/checkAutoLoader.php b/maintenance/checkAutoLoader.php
index d199b6feae..ea6c09f2bb 100644
--- a/maintenance/checkAutoLoader.php
+++ b/maintenance/checkAutoLoader.php
@@ -23,6 +23,11 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script to check classes definitions in the autoloader.
+ *
+ * @ingroup Maintenance
+ */
 class CheckAutoLoader extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/checkBadRedirects.php b/maintenance/checkBadRedirects.php
index bac2ff69a0..f8b8955c3a 100644
--- a/maintenance/checkBadRedirects.php
+++ b/maintenance/checkBadRedirects.php
@@ -1,7 +1,6 @@
 <?php
 /**
- * CheckBadRedirects - See if pages marked as being redirects
- * really are.
+ * Check that pages marked as being redirects really are.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -24,6 +23,11 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script to check that pages marked as being redirects really are.
+ *
+ * @ingroup Maintenance
+ */
 class CheckBadRedirects extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/checkImages.php b/maintenance/checkImages.php
index 484217d972..d7463ece28 100644
--- a/maintenance/checkImages.php
+++ b/maintenance/checkImages.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * Check images to see if they exist, are readable, etc etc
+ * Check images to see if they exist, are readable, etc.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -22,6 +22,11 @@
  */
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script to check images to see if they exist, are readable, etc.
+ *
+ * @ingroup Maintenance
+ */
 class CheckImages extends Maintenance {
 
 	public function __construct() {
diff --git a/maintenance/checkSyntax.php b/maintenance/checkSyntax.php
index 6137a95560..3019b8427a 100644
--- a/maintenance/checkSyntax.php
+++ b/maintenance/checkSyntax.php
@@ -23,6 +23,11 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script to check syntax of all PHP files in MediaWiki.
+ *
+ * @ingroup Maintenance
+ */
 class CheckSyntax extends Maintenance {
 
 	// List of files we're going to check
diff --git a/maintenance/checkUsernames.php b/maintenance/checkUsernames.php
index 9b98721db6..6a9294a307 100644
--- a/maintenance/checkUsernames.php
+++ b/maintenance/checkUsernames.php
@@ -1,8 +1,6 @@
 <?php
 /**
- * This script verifies that database usernames are actually valid.
- * An existing usernames can become invalid if User::isValidUserName()
- * is altered or if we change the $wgMaxNameChars
+ * Check that database usernames are actually valid.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -26,6 +24,14 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script to check that database usernames are actually valid.
+ *
+ * An existing usernames can become invalid if User::isValidUserName()
+ * is altered or if we change the $wgMaxNameChars
+ *
+ * @ingroup Maintenance
+ */
 class CheckUsernames extends Maintenance {
 
 	public function __construct() {
diff --git a/maintenance/convertLinks.php b/maintenance/convertLinks.php
index 85ef5c8c70..275d8fad19 100644
--- a/maintenance/convertLinks.php
+++ b/maintenance/convertLinks.php
@@ -1,7 +1,6 @@
 <?php
 /**
- * Convert from the old links schema (string->ID) to the new schema (ID->ID)
- * The wiki should be put into read-only mode while this script executes
+ * Convert from the old links schema (string->ID) to the new schema (ID->ID).
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -24,12 +23,20 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script to convert from the old links schema (string->ID)
+ * to the new schema (ID->ID).
+ *
+ * The wiki should be put into read-only mode while this script executes.
+ *
+ * @ingroup Maintenance
+ */
 class ConvertLinks extends Maintenance {
 	private $logPerformance;
 
 	public function __construct() {
 		parent::__construct();
-		$this->mDescription = "Convert from the old links schema (string->ID) to the new schema (ID->ID)
+		$this->mDescription = "Convert from the old links schema (string->ID) to the new schema (ID->ID).
 The wiki should be put into read-only mode while this script executes";
 
 		$this->addArg( 'logperformance', "Log performance to perfLogFilename.", false );
diff --git a/maintenance/convertUserOptions.php b/maintenance/convertUserOptions.php
index da6ff9b683..e666b65a13 100644
--- a/maintenance/convertUserOptions.php
+++ b/maintenance/convertUserOptions.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * Do each user sequentially, since accounts can't be deleted
+ * Convert user options to the new `user_properties` table.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -23,6 +23,13 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script to convert user options to the new `user_properties` table.
+ *
+ * Do each user sequentially, since accounts can't be deleted
+ *
+ * @ingroup Maintenance
+ */
 class ConvertUserOptions extends Maintenance {
 
 	private $mConversionCount = 0;
diff --git a/maintenance/copyFileBackend.php b/maintenance/copyFileBackend.php
index 314318faa2..07f619994d 100644
--- a/maintenance/copyFileBackend.php
+++ b/maintenance/copyFileBackend.php
@@ -2,12 +2,6 @@
 /**
  * Copy all files in one container of one backend to another.
  *
- * This can also be used to re-shard the files for one backend using the
- * config of second backend. The second backend should have the same config
- * as the first, except for it having a different name and different sharding
- * configuration. The backend should be made read-only while this runs.
- * After this script finishes, the old files in the containers can be deleted.
- *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
@@ -23,11 +17,23 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup Maintenance
  */
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Copy all files in one container of one backend to another.
+ *
+ * This can also be used to re-shard the files for one backend using the
+ * config of second backend. The second backend should have the same config
+ * as the first, except for it having a different name and different sharding
+ * configuration. The backend should be made read-only while this runs.
+ * After this script finishes, the old files in the containers can be deleted.
+ *
+ * @ingroup Maintenance
+ */
 class CopyFileBackend extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/createAndPromote.php b/maintenance/createAndPromote.php
index 0d7de9a964..3f328f9987 100644
--- a/maintenance/createAndPromote.php
+++ b/maintenance/createAndPromote.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * Maintenance script to create an account and grant it administrator rights
+ * Creates an account and grant it administrator rights.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -24,6 +24,11 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script to create an account and grant it administrator rights.
+ *
+ * @ingroup Maintenance
+ */
 class CreateAndPromote extends Maintenance {
 
 	public function __construct() {
@@ -76,4 +81,4 @@ class CreateAndPromote extends Maintenance {
 }
 
 $maintClass = "CreateAndPromote";
-require_once( RUN_MAINTENANCE_IF_MAIN );
\ No newline at end of file
+require_once( RUN_MAINTENANCE_IF_MAIN );
diff --git a/maintenance/deleteArchivedFiles.inc b/maintenance/deleteArchivedFiles.inc
index 2eacb73b9e..728997d081 100644
--- a/maintenance/deleteArchivedFiles.inc
+++ b/maintenance/deleteArchivedFiles.inc
@@ -17,9 +17,15 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup Maintenance
  */
 
+/**
+ * Core functions for deleteArchivedFiles.php
+ *
+ * @ingroup Maintenance
+ */
 class DeleteArchivedFilesImplementation {
 	static public function doDelete( $output, $force ) {
 		# Data should come off the master, wrapped in a transaction
@@ -62,4 +68,4 @@ class DeleteArchivedFilesImplementation {
 		$dbw->commit( __METHOD__ );
 		$output->handleOutput( "Done! [$count file(s)]\n" );
 	}
-}
\ No newline at end of file
+}
diff --git a/maintenance/deleteArchivedFiles.php b/maintenance/deleteArchivedFiles.php
index 6067c8077e..8709ee88bc 100644
--- a/maintenance/deleteArchivedFiles.php
+++ b/maintenance/deleteArchivedFiles.php
@@ -1,8 +1,9 @@
 <?php
-
 /**
  * Delete archived (non-current) files from the database
  *
+ * Based on deleteOldRevisions.php by Rob Church.
+ *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
@@ -18,14 +19,19 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup Maintenance
  * @author Aaron Schulz
- * Based on deleteOldRevisions.php by Rob Church
  */
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 require_once( dirname( __FILE__ ) . '/deleteArchivedFiles.inc' );
 
+/**
+ * Maintenance script to delete archived (non-current) files from the database.
+ *
+ * @ingroup Maintenance
+ */
 class DeleteArchivedFiles extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/deleteArchivedRevisions.php b/maintenance/deleteArchivedRevisions.php
index 0faa0abbff..353661a5c7 100644
--- a/maintenance/deleteArchivedRevisions.php
+++ b/maintenance/deleteArchivedRevisions.php
@@ -1,8 +1,9 @@
 <?php
-
 /**
  * Delete archived (deleted from public) revisions from the database
  *
+ * Shamelessly stolen from deleteOldRevisions.php by Rob Church :)
+ *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
@@ -18,14 +19,20 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup Maintenance
  * @author Aaron Schulz
- * Shamelessly stolen from deleteOldRevisions.php by Rob Church :)
  */
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 require_once( dirname( __FILE__ ) . '/deleteArchivedRevisions.inc' );
 
+/**
+ * Maintenance script to delete archived (deleted from public) revisions
+ * from the database.
+ *
+ * @ingroup Maintenance
+ */
 class DeleteArchivedRevisions extends Maintenance {
 	public function __construct() {
 		parent::__construct();
-- 
2.20.1