Improve documentation of maintenance scripts.

Change-Id: I2433d23544e808e16f28805f93183b1af2409c94
2012-07-08 22:47:27 +02:00 · 2012-07-08 22:47:27 +02:00 · a28e00cb4b
commit a28e00cb4b
parent 2e79d0168e
12 changed files with 108 additions and 19 deletions
--- 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;
--- 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 {

 	/**
--- 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() {
--- 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();
--- 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();
--- 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();
--- 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();
--- 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() {
--- 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();
--- 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() {
--- 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();
--- 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();