From 4a69fceb79b17168c6b284b302f51ed485cc6f40 Mon Sep 17 00:00:00 2001
From: Antoine Musso <hashar@free.fr>
Date: Tue, 10 Jul 2012 17:18:20 +0200
Subject: [PATCH] prettify documentation

Change-Id: Icfd267a94ac981b4c15e51add18c6d8ceb68454e
---
 includes/Defines.php           |  2 +-
 includes/api/ApiFormatXml.php  | 36 ++++++++++++++++++++++++++++------
 includes/parser/Parser.php     | 36 ++++++++++++++++++----------------
 includes/upload/UploadBase.php |  2 +-
 4 files changed, 51 insertions(+), 25 deletions(-)

diff --git a/includes/Defines.php b/includes/Defines.php
index d0f0c26b19..f7b41b8791 100644
--- a/includes/Defines.php
+++ b/includes/Defines.php
@@ -25,7 +25,7 @@
  */
 
 /**
- * @defgroup Constants
+ * @defgroup Constants MediaWiki constants
  */
 
 /**
diff --git a/includes/api/ApiFormatXml.php b/includes/api/ApiFormatXml.php
index ef2c54f59e..c16b62c60f 100644
--- a/includes/api/ApiFormatXml.php
+++ b/includes/api/ApiFormatXml.php
@@ -83,16 +83,40 @@ class ApiFormatXml extends ApiFormatBase {
 
 	/**
 	 * This method takes an array and converts it to XML.
+	 *
 	 * There are several noteworthy cases:
 	 *
-	 *  If array contains a key '_element', then the code assumes that ALL other keys are not important and replaces them with the value['_element'].
-	 *	Example:	name='root',  value = array( '_element'=>'page', 'x', 'y', 'z') creates <root>  <page>x</page>  <page>y</page>  <page>z</page> </root>
+	 * If array contains a key '_element', then the code assumes that ALL
+	 * other keys are not important and replaces them with the
+	 * value['_element'].
+	 *
+	 * @par Example:
+	 * @verbatim
+	 * name='root',  value = array( '_element'=>'page', 'x', 'y', 'z')
+	 * @endverbatim
+	 * creates:
+	 * @verbatim
+	 * <root>  <page>x</page>  <page>y</page>  <page>z</page> </root>
+	 * @endverbatim
+	 *
+	 * If any of the array's element key is '*', then the code treats all
+	 * other key->value pairs as attributes, and the value['*'] as the
+	 * element's content.
+	 *
+	 * @par Example:
+	 * @verbatim
+	 * name='root',  value = array( '*'=>'text', 'lang'=>'en', 'id'=>10)
+	 * @endverbatim
+	 * creates:
+	 * @verbatim
+	 * <root lang='en' id='10'>text</root>
+	 * @endverbatim
 	 *
-	 *  If any of the array's element key is '*', then the code treats all other key->value pairs as attributes, and the value['*'] as the element's content.
-	 *	Example:	name='root',  value = array( '*'=>'text', 'lang'=>'en', 'id'=>10)   creates  <root lang='en' id='10'>text</root>
+	 * Finally neither key is found, all keys become element names, and values
+	 * become element content.
 	 *
-	 * If neither key is found, all keys become element names, and values become element content.
-	 * The method is recursive, so the same rules apply to any sub-arrays.
+	 * @note The method is recursive, so the same rules apply to any
+	 * sub-arrays.
 	 *
 	 * @param $elemName
 	 * @param $elemValue
diff --git a/includes/parser/Parser.php b/includes/parser/Parser.php
index 6f6ffe01ee..94af6a8ffe 100644
--- a/includes/parser/Parser.php
+++ b/includes/parser/Parser.php
@@ -31,36 +31,38 @@
  * transformation of that wiki markup it into XHTML output / markup
  * (which in turn the browser understands, and can display).
  *
- * <pre>
- * There are five main entry points into the Parser class:
- * parse()
+ * There are seven main entry points into the Parser class:
+ *
+ * - Parser::parse()
  *     produces HTML output
- * preSaveTransform().
+ * - Parser::preSaveTransform().
  *     produces altered wiki markup.
- * preprocess()
+ * - Parser::preprocess()
  *     removes HTML comments and expands templates
- * cleanSig() / cleanSigInSig()
+ * - Parser::cleanSig() and Parser::cleanSigInSig()
  *     Cleans a signature before saving it to preferences
- * getSection()
+ * - Parser::getSection()
  *     Return the content of a section from an article for section editing
- * replaceSection()
+ * - Parser::replaceSection()
  *     Replaces a section by number inside an article
- * getPreloadText()
+ * - Parser::getPreloadText()
  *     Removes <noinclude> sections, and <includeonly> tags.
  *
  * Globals used:
  *    object: $wgContLang
  *
- * NOT $wgUser or $wgTitle or $wgRequest or $wgLang. Keep them away!
+ * @warning $wgUser or $wgTitle or $wgRequest or $wgLang. Keep them away!
  *
- * settings:
- *  $wgUseDynamicDates*, $wgInterwikiMagic*,
- *  $wgNamespacesWithSubpages, $wgAllowExternalImages*,
- *  $wgLocaltimezone, $wgAllowSpecialInclusion*,
- *  $wgMaxArticleSize*
+ * @par Settings:
+ * $wgLocaltimezone
+ * $wgNamespacesWithSubpages
  *
- *  * only within ParserOptions
- * </pre>
+ * @par Settings only within ParserOptions:
+ * $wgAllowExternalImages
+ * $wgAllowSpecialInclusion
+ * $wgInterwikiMagic
+ * $wgMaxArticleSize
+ * $wgUseDynamicDates
  *
  * @ingroup Parser
  */
diff --git a/includes/upload/UploadBase.php b/includes/upload/UploadBase.php
index 243ca925ff..0e647a910b 100644
--- a/includes/upload/UploadBase.php
+++ b/includes/upload/UploadBase.php
@@ -22,7 +22,7 @@
  */
 
 /**
- * @defgroup Upload
+ * @defgroup Upload Upload related
  */
 
 /**
-- 
2.20.1