From 2a7478b4fb3313d7b5d8f115feec2760a38a4057 Mon Sep 17 00:00:00 2001
From: Alexandre Emsenhuber <ialex.wiki@gmail.com>
Date: Mon, 3 Sep 2012 20:10:09 +0200
Subject: [PATCH] Improve documentation of maintenance scripts.

Change-Id: Id7a04ff816dc47a8cc81a4da5ab0dff26b688bd5
---
 maintenance/update.php                  |  5 +++++
 maintenance/updateArticleCount.php      | 10 ++++++++--
 maintenance/updateCollation.php         | 14 ++++++++++----
 maintenance/updateDoubleWidthSearch.php |  7 ++++++-
 maintenance/updateRestrictions.php      |  6 ++++++
 maintenance/updateSearchIndex.php       |  7 ++++++-
 maintenance/updateSpecialPages.php      |  9 +++++++--
 maintenance/userOptions.php             |  4 +---
 maintenance/waitForSlave.php            |  7 ++++++-
 9 files changed, 55 insertions(+), 14 deletions(-)

diff --git a/maintenance/update.php b/maintenance/update.php
index 78e88273a3..877f1366a3 100644
--- a/maintenance/update.php
+++ b/maintenance/update.php
@@ -34,6 +34,11 @@ if ( !function_exists( 'version_compare' ) || ( version_compare( phpversion(), '
 $wgUseMasterForMaintenance = true;
 require_once( __DIR__ . '/Maintenance.php' );
 
+/**
+ * Maintenance script to run database schema updates.
+ *
+ * @ingroup Maintenance
+ */
 class UpdateMediaWiki extends Maintenance {
 
 	function __construct() {
diff --git a/maintenance/updateArticleCount.php b/maintenance/updateArticleCount.php
index 730a1f64e3..4d49dd2dbb 100644
--- a/maintenance/updateArticleCount.php
+++ b/maintenance/updateArticleCount.php
@@ -1,7 +1,7 @@
 <?php
 /**
- * Maintenance script to provide a better count of the number of articles
- * and update the site statistics table, if desired
+ * Provide a better count of the number of articles
+ * and update the site statistics table, if desired.
  *
  * 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
@@ -25,6 +25,12 @@
 
 require_once( __DIR__ . '/Maintenance.php' );
 
+/**
+ * Maintenance script to provide a better count of the number of articles
+ * and update the site statistics table, if desired.
+ *
+ * @ingroup Maintenance
+ */
 class UpdateArticleCount extends Maintenance {
 
 	public function __construct() {
diff --git a/maintenance/updateCollation.php b/maintenance/updateCollation.php
index ec99c99e01..b732508f12 100644
--- a/maintenance/updateCollation.php
+++ b/maintenance/updateCollation.php
@@ -1,7 +1,7 @@
 <?php
 /**
- * Script will find all rows in the categorylinks table whose collation is
- * out-of-date (cl_collation != $wgCategoryCollation) and repopulate cl_sortkey
+ * Find all rows in the categorylinks table whose collation is out-of-date
+ * (cl_collation != $wgCategoryCollation) and repopulate cl_sortkey
  * using the page title and cl_sortkey_prefix.
  *
  * This program is free software; you can redistribute it and/or modify
@@ -28,6 +28,12 @@
 
 require_once( __DIR__ . '/Maintenance.php' );
 
+/**
+ * Maintenance script that will find all rows in the categorylinks table
+ * whose collation is out-of-date.
+ *
+ * @ingroup Maintenance
+ */
 class UpdateCollation extends Maintenance {
 	const BATCH_SIZE = 50; // Number of rows to process in one batch
 	const SYNC_INTERVAL = 20; // Wait for slaves after this many batches
@@ -53,8 +59,8 @@ TEXT;
 			'collation, though, so it may miss out-of-date rows with a different, ' .
 			'even older collation.', false, true );
 		$this->addOption( 'target-collation', 'Set this to the new collation type to ' .
-			'use instead of $wgCategoryCollation. Usually you should not use this, ' . 
-			'you should just update $wgCategoryCollation in LocalSettings.php.', 
+			'use instead of $wgCategoryCollation. Usually you should not use this, ' .
+			'you should just update $wgCategoryCollation in LocalSettings.php.',
 			false, true );
 		$this->addOption( 'dry-run', 'Don\'t actually change the collations, just ' .
 			'compile statistics.' );
diff --git a/maintenance/updateDoubleWidthSearch.php b/maintenance/updateDoubleWidthSearch.php
index bcceab3999..dc7398ad16 100644
--- a/maintenance/updateDoubleWidthSearch.php
+++ b/maintenance/updateDoubleWidthSearch.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * Script to normalize double-byte latin UTF-8 characters
+ * Normalize double-byte latin UTF-8 characters
  *
  * Usage: php updateDoubleWidthSearch.php
  *
@@ -25,6 +25,11 @@
 
 require_once( __DIR__ . '/Maintenance.php' );
 
+/**
+ * Maintenance script to normalize double-byte latin UTF-8 characters.
+ *
+ * @ingroup Maintenance
+ */
 class UpdateDoubleWidthSearch extends Maintenance {
 
 	public function __construct() {
diff --git a/maintenance/updateRestrictions.php b/maintenance/updateRestrictions.php
index 04e7f41c99..8699dc26b7 100644
--- a/maintenance/updateRestrictions.php
+++ b/maintenance/updateRestrictions.php
@@ -26,6 +26,12 @@
 
 require_once( __DIR__ . '/Maintenance.php' );
 
+/**
+ * Maintenance script that updates page_restrictions table from
+ * old page_restriction column.
+ *
+ * @ingroup Maintenance
+ */
 class UpdateRestrictions extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/updateSearchIndex.php b/maintenance/updateSearchIndex.php
index 59acc9a32d..2a71e7edc0 100644
--- a/maintenance/updateSearchIndex.php
+++ b/maintenance/updateSearchIndex.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * Script for periodic off-peak updating of the search index
+ * Periodic off-peak updating of the search index.
  *
  * Usage: php updateSearchIndex.php [-s START] [-e END] [-p POSFILE] [-l LOCKTIME] [-q]
  * Where START is the starting timestamp
@@ -30,6 +30,11 @@
 
 require_once( __DIR__ . '/Maintenance.php' );
 
+/**
+ * Maintenance script for periodic off-peak updating of the search index.
+ *
+ * @ingroup Maintenance
+ */
 class UpdateSearchIndex extends Maintenance {
 
 	public function __construct() {
diff --git a/maintenance/updateSpecialPages.php b/maintenance/updateSpecialPages.php
index c1e497da2e..3f1a90bb3f 100644
--- a/maintenance/updateSpecialPages.php
+++ b/maintenance/updateSpecialPages.php
@@ -1,7 +1,7 @@
 <?php
 /**
- * Run this script periodically if you have miser mode enabled, to refresh the
- * caches
+ * Update for cached special pages.
+ * Run this script periodically if you have miser mode enabled.
  *
  * 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( __DIR__ . '/Maintenance.php' );
 
+/**
+ * Maintenance script to update cached special pages.
+ *
+ * @ingroup Maintenance
+ */
 class UpdateSpecialPages extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/userOptions.php b/maintenance/userOptions.php
index 64368f63a7..2181e44ddd 100644
--- a/maintenance/userOptions.php
+++ b/maintenance/userOptions.php
@@ -1,8 +1,6 @@
 <?php
 /**
- * Script to change users skins on the fly.
- * This is for at least MediaWiki 1.10alpha (r19611) and have not been
- * tested with previous versions. It should probably work with 1.7+.
+ * Script to change users preferences on the fly.
  *
  * Made on an original idea by Fooey (freenode)
  *
diff --git a/maintenance/waitForSlave.php b/maintenance/waitForSlave.php
index 468e2395d0..655be43d74 100644
--- a/maintenance/waitForSlave.php
+++ b/maintenance/waitForSlave.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * Script to wait until slave lag goes under a certain value.
+ * Wait until slave lag goes under a certain value.
  *
  * 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( __DIR__ . '/Maintenance.php' );
 
+/**
+ * Maintenance script to wait until slave lag goes under a certain value.
+ *
+ * @ingroup Maintenance
+ */
 class WaitForSlave extends Maintenance {
 	public function __construct() {
 		$this->addArg( 'maxlag', 'How long to wait for the slaves, default 10 seconds', false );
-- 
2.20.1