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

Also contains a fix for Ia5a38311 (fae0550).

Change-Id: I630c83b48b66c5d8c97411082cabd731f316f42d
---
 includes/objectcache/ObjectCacheSessionHandler.php |  2 +-
 maintenance/showJobs.php                           | 11 +++++++++--
 maintenance/showStats.php                          |  8 +++++++-
 maintenance/sql.php                                |  5 +++++
 maintenance/sqlite.inc                             |  4 +++-
 maintenance/sqlite.php                             |  8 +++++++-
 maintenance/stats.php                              |  8 +++++++-
 maintenance/syncFileBackend.php                    |  7 +++++++
 8 files changed, 46 insertions(+), 7 deletions(-)

diff --git a/includes/objectcache/ObjectCacheSessionHandler.php b/includes/objectcache/ObjectCacheSessionHandler.php
index d90c9f11ab..f55da94d7e 100644
--- a/includes/objectcache/ObjectCacheSessionHandler.php
+++ b/includes/objectcache/ObjectCacheSessionHandler.php
@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * Session storage in object cache.
  *
  * This program is free software; you can redistribute it and/or modify
diff --git a/maintenance/showJobs.php b/maintenance/showJobs.php
index edcbdd63ee..1dceb7907f 100644
--- a/maintenance/showJobs.php
+++ b/maintenance/showJobs.php
@@ -1,9 +1,9 @@
 <?php
 /**
- * Based on runJobs.php
- *
  * Report number of jobs currently waiting in master database.
  *
+ * Based on runJobs.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
@@ -19,6 +19,7 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup Maintenance
  * @author Tim Starling
  * @author Antoine Musso
@@ -26,6 +27,12 @@
 
 require_once( __DIR__ . '/Maintenance.php' );
 
+/**
+ * Maintenance script that reports the number of jobs currently waiting
+ * in master database.
+ *
+ * @ingroup Maintenance
+ */
 class ShowJobs extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/showStats.php b/maintenance/showStats.php
index f16853d7e2..982c7cbb47 100644
--- a/maintenance/showStats.php
+++ b/maintenance/showStats.php
@@ -1,7 +1,7 @@
 <?php
 
 /**
- * Maintenance script to show the cached statistics.
+ * Show the cached statistics.
  * Give out the same output as [[Special:Statistics]]
  *
  * This program is free software; you can redistribute it and/or modify
@@ -19,6 +19,7 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @file
  * @ingroup Maintenance
  * @author Antoine Musso <hashar at free dot fr>
  * Based on initStats.php by:
@@ -30,6 +31,11 @@
 
 require_once( __DIR__ . '/Maintenance.php' );
 
+/**
+ * Maintenance script to show the cached statistics.
+ *
+ * @ingroup Maintenance
+ */
 class ShowStats extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/sql.php b/maintenance/sql.php
index 7483dcc76f..c3d0e62765 100644
--- a/maintenance/sql.php
+++ b/maintenance/sql.php
@@ -23,6 +23,11 @@
 
 require_once( __DIR__ . '/Maintenance.php' );
 
+/**
+ * Maintenance script that sends SQL queries from the specified file to the database.
+ *
+ * @ingroup Maintenance
+ */
 class MwSql extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/sqlite.inc b/maintenance/sqlite.inc
index 1f821917c1..a8a1fce680 100644
--- a/maintenance/sqlite.inc
+++ b/maintenance/sqlite.inc
@@ -23,6 +23,8 @@
 
 /**
  * This class contains code common to different SQLite-related maintenance scripts
+ *
+ * @ingroup Maintenance
  */
 class Sqlite {
 
@@ -85,4 +87,4 @@ class Sqlite {
 		$db->close();
 		return true;
 	}
- };
\ No newline at end of file
+ };
diff --git a/maintenance/sqlite.php b/maintenance/sqlite.php
index 7a22df598f..4085c59b29 100644
--- a/maintenance/sqlite.php
+++ b/maintenance/sqlite.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * Performs some operations specific to SQLite database backend
+ * Performs some operations specific to SQLite database backend.
  *
  * 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( __DIR__ . '/Maintenance.php' );
 
+/**
+ * Maintenance script that performs some operations specific to SQLite database backend.
+ *
+ * @ingroup Maintenance
+ */
 class SqliteMaintenance extends Maintenance {
 	public function __construct() {
 		parent::__construct();
diff --git a/maintenance/stats.php b/maintenance/stats.php
index cbea24b8ec..be448f9946 100644
--- a/maintenance/stats.php
+++ b/maintenance/stats.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * Show statistics from the cache
+ * Show statistics from the cache.
  *
  * 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( __DIR__ . '/Maintenance.php' );
 
+/**
+ * Maintenance script that shows statistics from the cache.
+ *
+ * @ingroup Maintenance
+ */
 class CacheStats extends Maintenance {
 
 	public function __construct() {
diff --git a/maintenance/syncFileBackend.php b/maintenance/syncFileBackend.php
index 18d57c30ba..2e1d1c3f59 100644
--- a/maintenance/syncFileBackend.php
+++ b/maintenance/syncFileBackend.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( __DIR__ . '/Maintenance.php' );
 
+/**
+ * Maintenance script that syncs one file backend to another based on
+ * the journal of later.
+ *
+ * @ingroup Maintenance
+ */
 class SyncFileBackend extends Maintenance {
 	public function __construct() {
 		parent::__construct();
-- 
2.20.1