From afd8ac8fb7109c40353a24e7a06e14d320cc41c8 Mon Sep 17 00:00:00 2001
From: Alexandre Emsenhuber <ialex.wiki@gmail.com>
Date: Fri, 7 Sep 2012 22:03:56 +0200
Subject: [PATCH] Improve documentation of maintenance scripts.

Change-Id: I768abad1ad4642263519d39c50c88437aed47e15
---
 maintenance/dev/includes/router.php           | 24 ++++++++++++++++---
 maintenance/language/alltrans.php             |  7 ++++++
 maintenance/language/checkDupeMessages.php    |  2 +-
 maintenance/language/countMessages.php        |  7 ++++++
 maintenance/language/date-formats.php         |  6 +++++
 maintenance/language/digit2html.php           |  8 +++++++
 maintenance/language/dumpMessages.php         | 10 ++++++--
 .../language/generateCollationData.php        |  4 +++-
 .../language/generateNormalizerData.php       |  2 ++
 9 files changed, 63 insertions(+), 7 deletions(-)

diff --git a/maintenance/dev/includes/router.php b/maintenance/dev/includes/router.php
index 95bb1faf6e..ac96f459d1 100644
--- a/maintenance/dev/includes/router.php
+++ b/maintenance/dev/includes/router.php
@@ -1,7 +1,25 @@
 <?php
-
-# Router for the php cli-server built-in webserver
-# http://ca2.php.net/manual/en/features.commandline.webserver.php
+/**
+ * Router for the php cli-server built-in webserver.
+ * http://www.php.net/manual/en/features.commandline.webserver.php
+ *
+ * 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
+ */
 
 if ( php_sapi_name() != 'cli-server' ) {
 	die( "This script can only be run by php's cli-server sapi." );
diff --git a/maintenance/language/alltrans.php b/maintenance/language/alltrans.php
index b537f9b70c..8caf8677f5 100644
--- a/maintenance/language/alltrans.php
+++ b/maintenance/language/alltrans.php
@@ -17,11 +17,18 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup MaintenanceLanguage
  */
 
 require_once( __DIR__ . '/../Maintenance.php' );
 
+/**
+ * Maintenance script that gets all messages as defined by the
+ * English language file.
+ *
+ * @ingroup MaintenanceLanguage
+ */
 class AllTrans extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/language/checkDupeMessages.php b/maintenance/language/checkDupeMessages.php
index 1888c4cd76..6abf7b44fa 100644
--- a/maintenance/language/checkDupeMessages.php
+++ b/maintenance/language/checkDupeMessages.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * Script to print out duplicates in message array
+ * Print out duplicates in message array
  *
  * 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/language/countMessages.php b/maintenance/language/countMessages.php
index d37d22e961..5058a5494b 100644
--- a/maintenance/language/countMessages.php
+++ b/maintenance/language/countMessages.php
@@ -17,11 +17,18 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup MaintenanceLanguage
  */
 
 require_once( __DIR__ . '/../Maintenance.php' );
 
+/**
+ * Maintenance script that counts how many messages we have defined
+ * for each language.
+ *
+ * @ingroup MaintenanceLanguage
+ */
 class CountMessages extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/language/date-formats.php b/maintenance/language/date-formats.php
index 505cb57b91..ed12b786ba 100644
--- a/maintenance/language/date-formats.php
+++ b/maintenance/language/date-formats.php
@@ -17,11 +17,17 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup MaintenanceLanguage
  */
 
 require_once( __DIR__ . '/../Maintenance.php' );
 
+/**
+ * Maintenance script that tests various language time and date functions.
+ *
+ * @ingroup MaintenanceLanguage
+ */
 class DateFormats extends Maintenance {
 
 	private $ts = '20010115123456';
diff --git a/maintenance/language/digit2html.php b/maintenance/language/digit2html.php
index 7e729b4c7d..9d4cbe7ea2 100644
--- a/maintenance/language/digit2html.php
+++ b/maintenance/language/digit2html.php
@@ -1,5 +1,7 @@
 <?php
 /**
+ * Check digit transformation
+ *
  * 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 MaintenanceLanguage
  */
 
 require_once( __DIR__ . '/../Maintenance.php' );
 
+/**
+ * Maintenance script that check digit transformation.
+ *
+ * @ingroup MaintenanceLanguage
+ */
 class Digit2Html extends Maintenance {
 
 	# A list of unicode numerals is available at:
diff --git a/maintenance/language/dumpMessages.php b/maintenance/language/dumpMessages.php
index 9292ce3051..0292d31451 100644
--- a/maintenance/language/dumpMessages.php
+++ b/maintenance/language/dumpMessages.php
@@ -18,18 +18,24 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup MaintenanceLanguage
- * @todo Make this more useful, right now just dumps $wgContentLang
+ * @todo Make this more useful, right now just dumps $wgContLang
  */
 
 require_once( __DIR__ . '/../Maintenance.php' );
 
+/**
+ * Maintenance script that dumps an entire language, using the keys from English.
+ *
+ * @ingroup MaintenanceLanguage
+ */
 class DumpMessages extends Maintenance {
 	public function __construct() {
 		parent::__construct();
 		$this->mDescription = "Dump an entire language, using the keys from English";
 	}
-	
+
 	public function execute() {
 		global $wgVersion;
 
diff --git a/maintenance/language/generateCollationData.php b/maintenance/language/generateCollationData.php
index c4a8e54320..e34d9a1308 100644
--- a/maintenance/language/generateCollationData.php
+++ b/maintenance/language/generateCollationData.php
@@ -17,14 +17,16 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
- * @ingroup Maintenance
  * @file
+ * @ingroup MaintenanceLanguage
  */
 
 require_once( __DIR__ .'/../Maintenance.php' );
 
 /**
  * Generate first letter data files for Collation.php
+ *
+ * @ingroup MaintenanceLanguage
  */
 class GenerateCollationData extends Maintenance {
 	/** The directory with source data files in it */
diff --git a/maintenance/language/generateNormalizerData.php b/maintenance/language/generateNormalizerData.php
index f3cc568221..54dfa39a5d 100644
--- a/maintenance/language/generateNormalizerData.php
+++ b/maintenance/language/generateNormalizerData.php
@@ -28,6 +28,8 @@ require_once( __DIR__ . '/../../includes/normal/UtfNormalUtil.php' );
 /**
  * Generates normalizer data files for Arabic and Malayalam.
  * For NFC see includes/normal.
+ *
+ * @ingroup MaintenanceLanguage
  */
 class GenerateNormalizerData extends Maintenance {
 	var $dataFile;
-- 
2.20.1