From 559277b2e34bbc8215bd508cb87f2c7aa08ad289 Mon Sep 17 00:00:00 2001
From: Sam Reed <reedy@users.mediawiki.org>
Date: Sun, 5 Jun 2011 15:10:11 +0000
Subject: [PATCH] * (bug 29265) Mediawiki API documentation incomplete

Add text about erroneous requests when sent to the api

Remove extra //, and add some documentation
---
 includes/api/ApiMain.php | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/includes/api/ApiMain.php b/includes/api/ApiMain.php
index f3ab32b92e..4b8b5307bb 100644
--- a/includes/api/ApiMain.php
+++ b/includes/api/ApiMain.php
@@ -295,6 +295,8 @@ class ApiMain extends ApiBase {
 	 *
 	 * Cache control values set here will only be used if the cache mode is not
 	 * private, see setCacheMode().
+	 *
+	 * @param $directives array
 	 */
 	public function setCacheControl( $directives ) {
 		$this->mCacheControl = $directives + $this->mCacheControl;
@@ -359,11 +361,9 @@ class ApiMain extends ApiBase {
 				wfDebugLog( 'exception', $e->getLogMessage() );
 			}
 
-			//
 			// Handle any kind of exception by outputing properly formatted error message.
 			// If this fails, an unhandled exception should be thrown so that global error
 			// handler will process and log it.
-			//
 
 			$errCode = $this->substituteResultWithError( $e );
 
@@ -601,7 +601,6 @@ class ApiMain extends ApiBase {
 		return true;
 	}
 
-
 	/**
 	 * Check for sufficient permissions to execute
 	 * @param $module ApiBase An Api module
@@ -786,9 +785,16 @@ class ApiMain extends ApiBase {
 			'**********************************************************************************************************',
 			'',
 			'Status:                All features shown on this page should be working, but the API',
-			'                       is still in active development, and  may change at any time.',
+			'                       is still in active development, and may change at any time.',
 			'                       Make sure to monitor our mailing list for any updates',
 			'',
+			'Erroneous requests:    When erroneous are sent to the API, a HTTP header will be sent',
+			'                       with the key "MediaWiki-API-Error" and then both the value of the',
+			'                       header and the error code sent back will be set to the same value',
+			'',
+			'                       In the case of an invalid action being passed, these will have a value',
+			'                       of "unknown_action"',
+			'',
 			'Documentation:         http://www.mediawiki.org/wiki/API',
 			'Mailing list:          http://lists.wikimedia.org/mailman/listinfo/mediawiki-api',
 			'Api Announcements:     http://lists.wikimedia.org/mailman/listinfo/mediawiki-api-announce',
@@ -1023,10 +1029,16 @@ class UsageException extends Exception {
 		$this->mExtraData = $extradata;
 	}
 
+	/**
+	 * @return string
+	 */
 	public function getCodeString() {
 		return $this->mCodestr;
 	}
 
+	/**
+	 * @return array
+	 */
 	public function getMessageArray() {
 		$result = array(
 			'code' => $this->mCodestr,
@@ -1038,6 +1050,9 @@ class UsageException extends Exception {
 		return $result;
 	}
 
+	/**
+	 * @return string
+	 */
 	public function __toString() {
 		return "{$this->getCodeString()}: {$this->getMessage()}";
 	}
-- 
2.20.1