Improve documentation of maintenance scripts.

Change-Id: I328a3d42a09f2b082ebc153c2f399793e23942d7

diff --git a/maintenance/attachLatest.php b/maintenance/attachLatest.php
index 6e09671..78cae8c 100644 (file)
--- 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 cfcac40..e4063f9 100644 (file)
--- 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 d199b6f..ea6c09f 100644 (file)
--- 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 bac2ff6..f8b8955 100644 (file)
--- 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 484217d..d7463ec 100644 (file)
--- 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 6137a95..3019b84 100644 (file)
--- 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 9b98721..6a9294a 100644 (file)
--- 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 85ef5c8..275d8fa 100644 (file)
--- 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 da6ff9b..e666b65 100644 (file)
--- 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 314318f..07f6199 100644 (file)
--- 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 0d7de9a..3f328f9 100644 (file)
--- 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 2eacb73..728997d 100644 (file)
--- 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 6067c80..8709ee8 100644 (file)
--- 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 0faa0ab..353661a 100644 (file)
--- 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();