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

diff --git a/includes/htmlform/HTMLForm.php b/includes/htmlform/HTMLForm.php
index 296de96..b57b69d 100644 (file)
--- 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 1d8f57a..bf86ab2 100644 (file)
--- 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