From 32515c4bda22850c614ee7f063a776b5c6e032c4 Mon Sep 17 00:00:00 2001
From: Alexandre Emsenhuber <ialex.wiki@gmail.com>
Date: Tue, 17 Jul 2012 07:40:40 +0200
Subject: [PATCH] Improve documentation of maintenance scripts.

Change-Id: If0af9922ede902c2c6f18b627d5810f3e888c944
---
 maintenance/deleteBatch.php       |  2 +-
 maintenance/edit.php              |  1 +
 maintenance/fixSlaveDesync.php    |  1 +
 maintenance/generateSitemap.php   |  7 ++++++-
 maintenance/getLagTimes.php       |  8 +++++++
 maintenance/getSlaveServer.php    |  8 ++++++-
 maintenance/getText.php           |  9 +++++++-
 maintenance/importDump.php        |  6 +++++-
 maintenance/importImages.inc      |  2 +-
 maintenance/importImages.php      |  5 ++---
 maintenance/importSiteScripts.php | 35 ++++++++++++++++++-------------
 maintenance/importTextFile.php    |  4 +---
 maintenance/initStats.php         |  7 ++++++-
 maintenance/install.php           | 10 +++++++--
 14 files changed, 75 insertions(+), 30 deletions(-)

diff --git a/maintenance/deleteBatch.php b/maintenance/deleteBatch.php
index 2a99fa1866..6860a5afa4 100644
--- a/maintenance/deleteBatch.php
+++ b/maintenance/deleteBatch.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * Deletes a batch of pages
+ * Deletes a batch of pages.
  * Usage: php deleteBatch.php [-u <user>] [-r <reason>] [-i <interval>] [listfile]
  * where
  *	[listfile] is a file where each line contains the title of a page to be
diff --git a/maintenance/edit.php b/maintenance/edit.php
index 211dc4edd1..13b3c49181 100644
--- a/maintenance/edit.php
+++ b/maintenance/edit.php
@@ -17,6 +17,7 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup Maintenance
  */
 
diff --git a/maintenance/fixSlaveDesync.php b/maintenance/fixSlaveDesync.php
index de6f652137..126eed2524 100644
--- a/maintenance/fixSlaveDesync.php
+++ b/maintenance/fixSlaveDesync.php
@@ -17,6 +17,7 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup Maintenance
  */
 
diff --git a/maintenance/generateSitemap.php b/maintenance/generateSitemap.php
index 7e83d5f659..a81e3d9e91 100644
--- a/maintenance/generateSitemap.php
+++ b/maintenance/generateSitemap.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * Creates a sitemap for the site
+ * Creates a sitemap for the site.
  *
  * Copyright © 2005, Ævar Arnfjörð Bjarmason, Jens Frank <jeluf@gmx.de> and
  * Brion Vibber <brion@pobox.com>
@@ -28,6 +28,11 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script that generates a sitemap for the site.
+ *
+ * @ingroup Maintenance
+ */
 class GenerateSitemap extends Maintenance {
 	const GS_MAIN = -2;
 	const GS_TALK = -1;
diff --git a/maintenance/getLagTimes.php b/maintenance/getLagTimes.php
index 0322fa2dc2..c47c61e4be 100644
--- a/maintenance/getLagTimes.php
+++ b/maintenance/getLagTimes.php
@@ -1,5 +1,7 @@
 <?php
 /**
+ * Display replication lag times.
+ *
  * 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
@@ -15,11 +17,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 displays replication lag times.
+ *
+ * @ingroup Maintenance
+ */
 class GetLagTimes extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/getSlaveServer.php b/maintenance/getSlaveServer.php
index 3d13bc4e59..0270052845 100644
--- a/maintenance/getSlaveServer.php
+++ b/maintenance/getSlaveServer.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * This script reports the hostname of a slave server.
+ * Reports the hostname of a slave server.
  *
  * 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,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 reports the hostname of a slave server.
+ *
+ * @ingroup Maintenance
+ */
 class GetSlaveServer extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/getText.php b/maintenance/getText.php
index eb04411722..34558b66f9 100644
--- a/maintenance/getText.php
+++ b/maintenance/getText.php
@@ -1,6 +1,7 @@
 <?php
 /**
- * Outputs page text to stdout, useful for command-line editing automation.
+ * Outputs page text to stdout.
+ * Useful for command-line editing automation.
  * Example: php getText.php "page title" | sed -e '...' | php edit.php "page title"
  *
  * This program is free software; you can redistribute it and/or modify
@@ -18,11 +19,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 outputs page text to stdout.
+ *
+ * @ingroup Maintenance
+ */
 class GetTextMaint extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/importDump.php b/maintenance/importDump.php
index 2ad0872f54..b6e0fe09e5 100644
--- a/maintenance/importDump.php
+++ b/maintenance/importDump.php
@@ -1,6 +1,8 @@
 <?php
 /**
- * Copyright (C) 2005 Brion Vibber <brion@pobox.com>
+ * Import XML dump files into the current wiki.
+ *
+ * Copyright © 2005 Brion Vibber <brion@pobox.com>
  * http://www.mediawiki.org/
  *
  * This program is free software; you can redistribute it and/or modify
@@ -25,6 +27,8 @@
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
 /**
+ * Maintenance script that imports XML dump files into the current wiki.
+ *
  * @ingroup Maintenance
  */
 class BackupReader extends Maintenance {
diff --git a/maintenance/importImages.inc b/maintenance/importImages.inc
index 5eb68f20b3..ac5d14432b 100644
--- a/maintenance/importImages.inc
+++ b/maintenance/importImages.inc
@@ -1,6 +1,6 @@
 <?php
 /**
- * Support functions for the importImages script
+ * Support functions for the importImages.php 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
diff --git a/maintenance/importImages.php b/maintenance/importImages.php
index bd077ff959..76ec565d6d 100644
--- a/maintenance/importImages.php
+++ b/maintenance/importImages.php
@@ -1,8 +1,7 @@
 <?php
-
 /**
- * Maintenance script to import one or more images from the local file system into
- * the wiki without using the web-based interface.
+ * Import one or more images from the local file system into the wiki without
+ * using the web-based interface.
  *
  * "Smart import" additions:
  * - aim: preserve the essential metadata (user, description) when importing medias from an existing wiki
diff --git a/maintenance/importSiteScripts.php b/maintenance/importSiteScripts.php
index 0ce93881bd..65ac65afd8 100644
--- a/maintenance/importSiteScripts.php
+++ b/maintenance/importSiteScripts.php
@@ -1,7 +1,6 @@
 <?php
 /**
- * Maintenance script to import all scripts in the MediaWiki namespace from a
- * local site.
+ * Import all scripts in the MediaWiki namespace from a local site.
  *
  * 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,12 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script to import all scripts in the MediaWiki namespace from a
+ * local site.
+ *
+ * @ingroup Maintenance
+ */
 class ImportSiteScripts extends Maintenance {
 	public function __construct() {
 		parent::__construct();
@@ -32,17 +37,17 @@ class ImportSiteScripts extends Maintenance {
 		$this->addArg( 'index', 'index.php base url' );
 		$this->addOption( 'username', 'User name of the script importer' );
 	}
-	
+
 	public function execute() {
 		global $wgUser;
 
 		$user = User::newFromName( $this->getOption( 'username', 'ScriptImporter' ) );
 		$wgUser = $user;
-		
+
 		$baseUrl = $this->getArg( 1 );
 		$pageList = $this->fetchScriptList();
 		$this->output( 'Importing ' . count( $pageList ) . " pages\n" );
-		
+
 		foreach ( $pageList as $page ) {
 			$title = Title::makeTitleSafe( NS_MEDIAWIKI, $page );
 			if ( !$title ) {
@@ -51,34 +56,34 @@ class ImportSiteScripts extends Maintenance {
 			}
 
 			$this->output( "Importing $page\n" );
-			$url = wfAppendQuery( $baseUrl, array( 
-				'action' => 'raw', 
+			$url = wfAppendQuery( $baseUrl, array(
+				'action' => 'raw',
 				'title' => "MediaWiki:{$page}" ) );
 			$text = Http::get( $url );
 
 			$wikiPage = WikiPage::factory( $title );
 			$wikiPage->doEdit( $text, "Importing from $url", 0, false, $user );
 		}
-		
+
 	}
-	
+
 	protected function fetchScriptList() {
-		$data = array( 
+		$data = array(
 			'action' => 'query',
 			'format' => 'php',//'json',
 			'list' => 'allpages',
 			'apnamespace' => '8',
-			'aplimit' => '500', 
+			'aplimit' => '500',
 		);
 		$baseUrl = $this->getArg( 0 );
 		$pages = array();
-		
+
 		do {
 			$url = wfAppendQuery( $baseUrl, $data );
 			$strResult = Http::get( $url );
 			//$result = FormatJson::decode( $strResult ); // Still broken
 			$result = unserialize( $strResult );
-			
+
 			if ( !empty( $result['query']['allpages'] ) ) {
 				foreach ( $result['query']['allpages'] as $page ) {
 					if ( substr( $page['title'], -3 ) === '.js' ) {
@@ -92,9 +97,9 @@ class ImportSiteScripts extends Maintenance {
 				$this->output( "Fetching new batch from {$data['apfrom']}\n" );
 			}
 		} while ( isset( $result['query-continue'] ) );
-		
+
 		return $pages;
-		
+
 	}
 }
 
diff --git a/maintenance/importTextFile.php b/maintenance/importTextFile.php
index ec9ff001ad..5623fb06c2 100644
--- a/maintenance/importTextFile.php
+++ b/maintenance/importTextFile.php
@@ -1,8 +1,6 @@
 <?php
-
 /**
- * Maintenance script allows creating or editing pages using
- * the contents of a text file
+ * Create or edit pages using the contents of a text file.
  *
  * 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
diff --git a/maintenance/initStats.php b/maintenance/initStats.php
index eab9c8df68..35918bbdb5 100644
--- a/maintenance/initStats.php
+++ b/maintenance/initStats.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * Maintenance script to re-initialise or update the site statistics table
+ * Re-initialise or update the site statistics 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
@@ -25,6 +25,11 @@
 
 require_once( dirname( __FILE__ ) . '/Maintenance.php' );
 
+/**
+ * Maintenance script to re-initialise or update the site statistics table
+ *
+ * @ingroup Maintenance
+ */
 class InitStats extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/install.php b/maintenance/install.php
index 8e0b2e1395..6339773aa2 100644
--- a/maintenance/install.php
+++ b/maintenance/install.php
@@ -1,6 +1,7 @@
 <?php
-
 /**
+ * CLI-based MediaWiki installation and configuration.
+ *
  * 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
@@ -16,8 +17,8 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup Maintenance
- * @see wfWaitForSlaves()
  */
 
 if ( !function_exists( 'version_compare' ) || ( version_compare( phpversion(), '5.3.2' ) < 0 ) ) {
@@ -31,6 +32,11 @@ define( 'MEDIAWIKI_INSTALL', true );
 
 require_once( dirname( dirname( __FILE__ ) )."/maintenance/Maintenance.php" );
 
+/**
+ * Maintenance script to install and configure MediaWiki
+ *
+ * @ingroup Maintenance
+ */
 class CommandLineInstaller extends Maintenance {
 	function __construct() {
 		parent::__construct();
-- 
2.20.1