From 02e15ebd0ba7690bd499ab0d29a4f0d631b8a055 Mon Sep 17 00:00:00 2001
From: Alexandre Emsenhuber <ialex.wiki@gmail.com>
Date: Tue, 10 Jul 2012 18:50:19 +0200
Subject: [PATCH] Improve documentation of maintenance scripts.

Change-Id: I0e2869970c46f4fd14b792f2978cc1ba9d8550be
---
 maintenance/dumpUploads.php                 |  9 ++++++++-
 maintenance/edit.php                        |  7 ++++++-
 maintenance/fetchText.php                   |  8 +++++++-
 maintenance/fileOpPerfTest.php              |  7 ++++++-
 maintenance/findHooks.php                   |  5 +++++
 maintenance/fixDoubleRedirects.php          | 11 ++++++++---
 maintenance/fixExtLinksProtocolRelative.php |  7 +++++++
 maintenance/fixSlaveDesync.php              |  8 ++++++++
 maintenance/fixTimestamps.php               | 17 ++++++++++++-----
 maintenance/fixUserRegistration.php         |  6 ++++++
 maintenance/formatInstallDoc.php            |  7 +++++++
 11 files changed, 80 insertions(+), 12 deletions(-)

diff --git a/maintenance/dumpUploads.php b/maintenance/dumpUploads.php
index 919bb4df93..b16b0c2929 100644
--- a/maintenance/dumpUploads.php
+++ b/maintenance/dumpUploads.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * Dump a the list of files uploaded, for feeding to tar or similar
+ * Dump a the list of files uploaded, for feeding to tar or similar.
  *
  * 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
@@ -17,11 +17,18 @@
  * 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' );
 
+/**
+ * Maintenance script to dump a the list of files uploaded,
+ * for feeding to tar or similar.
+ *
+ * @ingroup Maintenance
+ */
 class UploadDumper extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/edit.php b/maintenance/edit.php
index 88573714a3..211dc4edd1 100644
--- a/maintenance/edit.php
+++ b/maintenance/edit.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * Make an edit
+ * Make a page edit.
  *
  * 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 make a page edit.
+ *
+ * @ingroup Maintenance
+ */
 class EditCLI extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/fetchText.php b/maintenance/fetchText.php
index 3b43bcd503..28330814c3 100644
--- a/maintenance/fetchText.php
+++ b/maintenance/fetchText.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * Communications protocol...
+ * Communications protocol.
  * This is used by dumpTextPass.php when the --spawn option is present.
  *
  * This program is free software; you can redistribute it and/or modify
@@ -18,11 +18,17 @@
  * 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' );
 
+/**
+ * Maintenance script used to fetch page text in a subprocess.
+ *
+ * @ingroup Maintenance
+ */
 class FetchText extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/fileOpPerfTest.php b/maintenance/fileOpPerfTest.php
index b16bd95352..69a2a7824b 100644
--- a/maintenance/fileOpPerfTest.php
+++ b/maintenance/fileOpPerfTest.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * Maintenance script to test fileop performance
+ * Test for fileop performance.
  *
  * 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
@@ -27,6 +27,11 @@ error_reporting( E_ALL );
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script to test fileop performance.
+ *
+ * @ingroup Maintenance
+ */
 class TestFileOpPerformance extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/findHooks.php b/maintenance/findHooks.php
index b8512e55e6..e4fa5deee1 100644
--- a/maintenance/findHooks.php
+++ b/maintenance/findHooks.php
@@ -36,6 +36,11 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script that compares documented and actually present mismatches.
+ *
+ * @ingroup Maintenance
+ */
 class FindHooks extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/fixDoubleRedirects.php b/maintenance/fixDoubleRedirects.php
index c1d14dd850..e52c6c34bf 100644
--- a/maintenance/fixDoubleRedirects.php
+++ b/maintenance/fixDoubleRedirects.php
@@ -1,8 +1,8 @@
 <?php
 /**
- * Script to fix double redirects.
+ * Fix double redirects.
  *
- * Copyright (C) 2011 Ilmari Karonen <nospam@vyznev.net>
+ * Copyright © 2011 Ilmari Karonen <nospam@vyznev.net>
  * http://www.mediawiki.org/
  *
  * This program is free software; you can redistribute it and/or modify
@@ -27,13 +27,18 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script that fixes double redirects.
+ *
+ * @ingroup Maintenance
+ */
 class FixDoubleRedirects extends Maintenance {
 	public function __construct() {
 		parent::__construct();
 		$this->mDescription = "Script to fix double redirects";
 		$this->addOption( 'async', 'Don\'t fix anything directly, just queue the jobs' );
 		$this->addOption( 'title', 'Fix only redirects pointing to this page', false, true );
-		$this->addOption( 'dry-run', 'Perform a dry run, fix nothing' );		
+		$this->addOption( 'dry-run', 'Perform a dry run, fix nothing' );
 	}
 
 	public function execute() {
diff --git a/maintenance/fixExtLinksProtocolRelative.php b/maintenance/fixExtLinksProtocolRelative.php
index 0cabe8160e..d247862f5f 100644
--- a/maintenance/fixExtLinksProtocolRelative.php
+++ b/maintenance/fixExtLinksProtocolRelative.php
@@ -19,11 +19,18 @@
  * 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' );
 
+/**
+ * Maintenance script that fixes any entriy for protocol-relative URLs
+ * in the externallinks table.
+ *
+ * @ingroup Maintenance
+ */
 class FixExtLinksProtocolRelative extends LoggedUpdateMaintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/fixSlaveDesync.php b/maintenance/fixSlaveDesync.php
index 7731d3e3b7..de6f652137 100644
--- a/maintenance/fixSlaveDesync.php
+++ b/maintenance/fixSlaveDesync.php
@@ -1,5 +1,7 @@
 <?php
 /**
+ * Fix erroneous page_latest values due to slave desynchronisation.
+ *
  * 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
@@ -20,6 +22,12 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script that fixes erroneous page_latest values
+ * due to slave desynchronisation.
+ *
+ * @ingroup Maintenance
+ */
 class FixSlaveDesync extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/fixTimestamps.php b/maintenance/fixTimestamps.php
index 3e3bd0a50a..3a952512de 100644
--- a/maintenance/fixTimestamps.php
+++ b/maintenance/fixTimestamps.php
@@ -1,10 +1,10 @@
 <?php
 /**
- * This script fixes timestamp corruption caused by one or more webservers
- * temporarily being set to the wrong time. The time offset must be known and
- * consistent. Start and end times (in 14-character format) restrict the search,
- * and must bracket the damage. There must be a majority of good timestamps in the
- * search period.
+ * Fixes timestamp corruption caused by one or more webservers temporarily
+ * being set to the wrong time.
+ * The time offset must be known and consistent. Start and end times
+ * (in 14-character format) restrict the search, and must bracket the damage.
+ * There must be a majority of good timestamps in the search period.
  *
  * 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
@@ -21,11 +21,18 @@
  * 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' );
 
+/**
+ * Maintenance script that fixes timestamp corruption caused by one or
+ * more webservers temporarily being set to the wrong time.
+ *
+ * @ingroup Maintenance
+ */
 class FixTimestamps extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/fixUserRegistration.php b/maintenance/fixUserRegistration.php
index d4ff7c23a2..4eca3967d3 100644
--- a/maintenance/fixUserRegistration.php
+++ b/maintenance/fixUserRegistration.php
@@ -18,11 +18,17 @@
  * 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' );
 
+/**
+ * Maintenance script that fixes the user_registration field.
+ *
+ * @ingroup Maintenance
+ */
 class FixUserRegistration extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/formatInstallDoc.php b/maintenance/formatInstallDoc.php
index fa98813f62..474caabc8d 100644
--- a/maintenance/formatInstallDoc.php
+++ b/maintenance/formatInstallDoc.php
@@ -1,5 +1,7 @@
 <?php
 /**
+ * Format RELEASE-NOTE file to wiki text or HTML markup.
+ *
  * 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
@@ -21,6 +23,11 @@
 
 require_once( dirname( __FILE__ ) .'/Maintenance.php' );
 
+/**
+ * Maintenance script that formats RELEASE-NOTE file to wiki text or HTML markup.
+ *
+ * @ingroup Maintenance
+ */
 class MaintenanceFormatInstallDoc extends Maintenance {
 	function __construct() {
 		parent::__construct();
-- 
2.20.1