From 0188fe7d5eda87f40e1c5908aaa659bc8a7d5b4c Mon Sep 17 00:00:00 2001
From: Brad Jorsch <bjorsch@wikimedia.org>
Date: Thu, 3 Jul 2014 11:11:04 -0400
Subject: [PATCH] HTMLForm submission callback documentation updates

The possibilities for the submission callback return value were
documented in three different places, and none were entirely correct.
Related documentation could also use a cleanup.

Change-Id: Ib3621a0d5ba24c481f3117b547bca70d4ca50ba2
---
 includes/htmlform/HTMLForm.php           | 20 +++++++++++---------
 includes/specialpage/FormSpecialPage.php |  5 +++--
 2 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/includes/htmlform/HTMLForm.php b/includes/htmlform/HTMLForm.php
index 296de96f6e..b57b69d339 100644
--- a/includes/htmlform/HTMLForm.php
+++ b/includes/htmlform/HTMLForm.php
@@ -434,9 +434,12 @@ class HTMLForm extends ContextSource {
 	 * Validate all the fields, and call the submission callback
 	 * function if everything is kosher.
 	 * @throws MWException
-	 * @return mixed Bool true == Successful submission, Bool false
-	 *     == No submission attempted, anything else == Error to
-	 *     display.
+	 * @return bool|string|array|Status
+	 *     - Bool true or a good Status object indicates success,
+	 *     - Bool false indicates no submission was attempted,
+	 *     - Anything else indicates failure. The value may be a fatal Status
+	 *       object, an HTML string, or an array of arrays (message keys and
+	 *       params) or strings (message keys)
 	 */
 	function trySubmit() {
 		$this->mWasSubmitted = true;
@@ -503,10 +506,9 @@ class HTMLForm extends ContextSource {
 	 * Set a callback to a function to do something with the form
 	 * once it's been successfully validated.
 	 *
-	 * @param string $cb Function name.  The function will be passed
-	 *     the output from HTMLForm::filterDataForSubmit, and must
-	 *     return Bool true on success, Bool false if no submission
-	 *     was attempted, or String HTML output to display on error.
+	 * @param callable $cb The function will be passed the output from
+	 *   HTMLForm::filterDataForSubmit and this HTMLForm object, and must
+	 *   return as documented for HTMLForm::trySubmit
 	 *
 	 * @return HTMLForm $this for chaining calls (since 1.20)
 	 */
@@ -734,7 +736,7 @@ class HTMLForm extends ContextSource {
 	 * Moreover, when doing method chaining this should be the very last method
 	 * call just after prepareForm().
 	 *
-	 * @param mixed $submitResult Mixed output from HTMLForm::trySubmit()
+	 * @param bool|string|array|Status $submitResult Output from HTMLForm::trySubmit()
 	 *
 	 * @return Nothing, should be last call
 	 */
@@ -745,7 +747,7 @@ class HTMLForm extends ContextSource {
 	/**
 	 * Returns the raw HTML generated by the form
 	 *
-	 * @param mixed $submitResult Mixed output from HTMLForm::trySubmit()
+	 * @param bool|string|array|Status $submitResult Output from HTMLForm::trySubmit()
 	 *
 	 * @return string
 	 */
diff --git a/includes/specialpage/FormSpecialPage.php b/includes/specialpage/FormSpecialPage.php
index 1d8f57a221..bf86ab2e1a 100644
--- a/includes/specialpage/FormSpecialPage.php
+++ b/includes/specialpage/FormSpecialPage.php
@@ -114,9 +114,10 @@ abstract class FormSpecialPage extends SpecialPage {
 	/**
 	 * Process the form on POST submission.
 	 * @param array $data
-	 * @return bool|array True for success, false for didn't-try, array of errors on failure
+	 * @param HTMLForm $form
+	 * @return bool|string|array|Status As documented for HTMLForm::trySubmit.
 	 */
-	abstract public function onSubmit( array $data );
+	abstract public function onSubmit( array $data /* $form = null */ );
 
 	/**
 	 * Do something exciting on successful processing of the form, most likely to show a
-- 
2.20.1