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 7ec1b0f..7a84fed 100644 (file)
--- 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;