From a28e00cb4b900dfbeca078369654854364dccb47 Mon Sep 17 00:00:00 2001
From: Alexandre Emsenhuber <ialex.wiki@gmail.com>
Date: Sun, 8 Jul 2012 22:47:27 +0200
Subject: [PATCH] Improve documentation of maintenance scripts.

Change-Id: I2433d23544e808e16f28805f93183b1af2409c94
---
 maintenance/cleanupPreferences.php      | 25 ++++++++++++++++++++++++-
 maintenance/deleteArchivedRevisions.inc |  9 +++++++--
 maintenance/deleteBatch.php             |  6 ++++++
 maintenance/deleteDefaultMessages.php   |  7 +++++++
 maintenance/deleteImageMemcached.php    |  8 +++++++-
 maintenance/deleteOldRevisions.php      |  7 ++++++-
 maintenance/deleteOrphanedRevisions.php | 11 ++++++++---
 maintenance/deleteRevision.php          |  7 +++++++
 maintenance/deleteSelfExternals.php     | 14 ++++++++------
 maintenance/dumpIterator.php            | 13 ++++++++++++-
 maintenance/dumpLinks.php               | 12 +++++++++---
 maintenance/dumpSisterSites.php         |  8 +++++++-
 12 files changed, 108 insertions(+), 19 deletions(-)

diff --git a/maintenance/cleanupPreferences.php b/maintenance/cleanupPreferences.php
index 4a52d106f9..706f87fb92 100755
--- a/maintenance/cleanupPreferences.php
+++ b/maintenance/cleanupPreferences.php
@@ -1,12 +1,35 @@
 <?php
 /**
- * Description: This script takes $wgHiddenPrefs and removes their preference from the DB. [[bugzilla:30976]]
+ * Remove hidden preferences from the database.
+ *
+ * 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
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * http://www.gnu.org/copyleft/gpl.html
+ *
+ * @file
  * @author TyA <tya.wiki@gmail.com>
+ * @see [[bugzilla:30976]]
  * @ingroup Maintenance
  */
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script that removes hidden preferences from the database.
+ *
+ * @ingroup Maintenance
+ */
 class CleanupPreferences extends Maintenance {
 	public function execute() {
 		global $wgHiddenPrefs;
diff --git a/maintenance/deleteArchivedRevisions.inc b/maintenance/deleteArchivedRevisions.inc
index 197ffab581..414d41adb6 100644
--- a/maintenance/deleteArchivedRevisions.inc
+++ b/maintenance/deleteArchivedRevisions.inc
@@ -1,7 +1,6 @@
 <?php
-
 /**
- * Delete archived (deleted from public) revisions from the database
+ * Helper methods for the deleteArchivedRevisions.php maintenance script.
  *
  * 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
@@ -18,9 +17,15 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup Maintenance
  */
 
+/**
+ * Helper methods for the deleteArchivedRevisions.php maintenance script.
+ *
+ * @ingroup Maintenance
+ */
 class DeleteArchivedRevisionsImplementation {
 
 	/**
diff --git a/maintenance/deleteBatch.php b/maintenance/deleteBatch.php
index 8963ae1b55..2a99fa1866 100644
--- a/maintenance/deleteBatch.php
+++ b/maintenance/deleteBatch.php
@@ -24,11 +24,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 to delete a batch of pages.
+ *
+ * @ingroup Maintenance
+ */
 class DeleteBatch extends Maintenance {
 
 	public function __construct() {
diff --git a/maintenance/deleteDefaultMessages.php b/maintenance/deleteDefaultMessages.php
index 4f5889b17e..540d225e67 100644
--- a/maintenance/deleteDefaultMessages.php
+++ b/maintenance/deleteDefaultMessages.php
@@ -18,11 +18,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 deletes all pages in the MediaWiki namespace
+ * which were last edited by "MediaWiki default".
+ *
+ * @ingroup Maintenance
+ */
 class DeleteDefaultMessages extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/deleteImageMemcached.php b/maintenance/deleteImageMemcached.php
index 007f0d17f6..2029b57106 100644
--- a/maintenance/deleteImageMemcached.php
+++ b/maintenance/deleteImageMemcached.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * This script delete image information from the cache.
+ * Delete image information from the object cache.
  *
  * Usage example:
  * php deleteImageMemcached.php --until "2005-09-05 00:00:00" --sleep 0
@@ -20,11 +20,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 deletes image information from the object cache.
+ *
+ * @ingroup Maintenance
+ */
 class DeleteImageCache extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/deleteOldRevisions.php b/maintenance/deleteOldRevisions.php
index 8347a29352..45a6b343c1 100644
--- a/maintenance/deleteOldRevisions.php
+++ b/maintenance/deleteOldRevisions.php
@@ -1,5 +1,4 @@
 <?php
-
 /**
  * Delete old (non-current) revisions from the database
  *
@@ -18,12 +17,18 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup Maintenance
  * @author Rob Church <robchur@gmail.com>
  */
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script that deletes old (non-current) revisions from the database.
+ *
+ * @ingroup Maintenance
+ */
 class DeleteOldRevisions extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/deleteOrphanedRevisions.php b/maintenance/deleteOrphanedRevisions.php
index 9fe5794302..13b9c91bf9 100644
--- a/maintenance/deleteOrphanedRevisions.php
+++ b/maintenance/deleteOrphanedRevisions.php
@@ -1,8 +1,7 @@
 <?php
-
 /**
- * Maintenance script to delete revisions which refer to a nonexisting page
- * Sometimes manual deletion done in a rush leaves crap in the database
+ * Delete revisions which refer to a nonexisting page.
+ * Sometimes manual deletion done in a rush leaves crap in the database.
  *
  * 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
@@ -19,6 +18,7 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup Maintenance
  * @author Rob Church <robchur@gmail.com>
  * @todo More efficient cleanup of text records
@@ -26,6 +26,11 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script that deletes revisions which refer to a nonexisting page.
+ *
+ * @ingroup Maintenance
+ */
 class DeleteOrphanedRevisions extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/deleteRevision.php b/maintenance/deleteRevision.php
index 5e8ecaacc1..fe3b5151a8 100644
--- a/maintenance/deleteRevision.php
+++ b/maintenance/deleteRevision.php
@@ -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 that deletes one or more revisions by moving them
+ * to the archive table.
+ *
+ * @ingroup Maintenance
+ */
 class DeleteRevision extends Maintenance {
 
 	public function __construct() {
diff --git a/maintenance/deleteSelfExternals.php b/maintenance/deleteSelfExternals.php
index 447d3bda8f..162dcb4f73 100644
--- a/maintenance/deleteSelfExternals.php
+++ b/maintenance/deleteSelfExternals.php
@@ -1,10 +1,6 @@
 <?php
 /**
- * We want to make this whole thing as seamless as possible to the
- * end-user. Unfortunately, we can't do _all_ of the work in the class
- * because A) included files are not in global scope, but in the scope
- * of their caller, and B) MediaWiki has way too many globals. So instead
- * we'll kinda fake it, and do the requires() inline. <3 PHP
+ * Delete self-references to $wgServer from the externallinks 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
@@ -21,12 +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 that deletes self-references to $wgServer
+ * from the externallinks table.
+ *
+ * @ingroup Maintenance
+ */
 class DeleteSelfExternals extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/dumpIterator.php b/maintenance/dumpIterator.php
index 470bc56eb2..4c04d860b6 100644
--- a/maintenance/dumpIterator.php
+++ b/maintenance/dumpIterator.php
@@ -4,7 +4,8 @@
  * Used as a base class for CompareParsers and PreprocessDump.
  * We implement below the simple task of searching inside a dump.
  *
- * Copyright (C) 2011 Platonides - http://www.mediawiki.org/
+ * Copyright © 2011 Platonides
+ * http://www.mediawiki.org/
  *
  * 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 +28,11 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Base class for interating over a dump.
+ *
+ * @ingroup Maintenance
+ */
 abstract class DumpIterator extends Maintenance {
 
 	private $count = 0;
@@ -141,6 +147,11 @@ abstract class DumpIterator extends Maintenance {
 	abstract public function processRevision( $rev );
 }
 
+/**
+ * Maintenance script that runs a regex in the revisions from a dump.
+ *
+ * @ingroup Maintenance
+ */
 class SearchDump extends DumpIterator {
 
 	public function __construct() {
diff --git a/maintenance/dumpLinks.php b/maintenance/dumpLinks.php
index 0101dc8dc1..ad440e70f2 100644
--- a/maintenance/dumpLinks.php
+++ b/maintenance/dumpLinks.php
@@ -1,8 +1,5 @@
 <?php
 /**
- * Copyright (C) 2005 Brion Vibber <brion@pobox.com>
- * http://www.mediawiki.org/
- *
  * Quick demo hack to generate a plaintext link dump,
  * per the proposed wiki link database standard:
  * http://www.usemod.com/cgi-bin/mb.pl?LinkDatabase
@@ -11,6 +8,9 @@
  * Does not include interwiki or URL links.
  * Dumps ASCII text to stdout; command-line.
  *
+ * Copyright © 2005 Brion Vibber <brion@pobox.com>
+ * http://www.mediawiki.org/
+ *
  * 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
@@ -26,11 +26,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 generates a plaintext link dump.
+ *
+ * @ingroup Maintenance
+ */
 class DumpLinks extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/dumpSisterSites.php b/maintenance/dumpSisterSites.php
index f5abcd1b81..5dbb5e2360 100644
--- a/maintenance/dumpSisterSites.php
+++ b/maintenance/dumpSisterSites.php
@@ -3,7 +3,7 @@
  * Quickie page name dump script for SisterSites usage.
  * http://www.eekim.com/cgi-bin/wiki.pl?SisterSites
  *
- * Copyright (C) 2006 Brion Vibber <brion@pobox.com>
+ * Copyright © 2006 Brion Vibber <brion@pobox.com>
  * http://www.mediawiki.org/
  *
  * This program is free software; you can redistribute it and/or modify
@@ -21,11 +21,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 generates a page name dump for SisterSites usage.
+ *
+ * @ingroup Maintenance
+ */
 class DumpSisterSites extends Maintenance {
 	public function __construct() {
 		parent::__construct();
-- 
2.20.1