From: Bryan Davis <bd808@wikimedia.org>
Date: Tue, 8 Oct 2013 17:51:32 +0000 (-0600)
Subject: Add doc comment to Status explaining use
X-Git-Tag: 1.31.0-rc.0~18572
X-Git-Url: http://git.cyclocoop.org/%22%20.%20generer_url_ecrire%28%22messagerie%22%29%20.%20%22?a=commitdiff_plain;h=bf4c2b6aff5ef893f16c242580df5188dba86476;p=lhc%2Fweb%2Fwiklou.git

Add doc comment to Status explaining use

Tim posted a nice explanation of the recommended pattern for using the
Status object to wikitech-l. This change copies that explanation into
the phpdoc comment block of the Status class in an attempt to propagate
the meme.

Change-Id: Ia98543caaa829cad443abf0f0f5038b3de943ef8
---

diff --git a/includes/Status.php b/includes/Status.php
index 7ec1b0f68c..7a84fed109 100644
--- a/includes/Status.php
+++ b/includes/Status.php
@@ -31,6 +31,11 @@
  * An operation which is not OK should have errors so that the user can be
  * informed as to what went wrong. Calling the fatal() function sets an error
  * message and simultaneously switches off the OK flag.
+ *
+ * The recommended pattern for Status objects is to return a Status object
+ * unconditionally, i.e. both on success and on failure -- so that the
+ * developer of the calling code is reminded that the function can fail, and
+ * so that a lack of error-handling will be explicit.
  */
 class Status {
 	var $ok = true;