From: Brad Jorsch <bjorsch@wikimedia.org>
Date: Mon, 25 Sep 2017 16:14:55 +0000 (-0400)
Subject: Update documentation for IApiMessage interface
X-Git-Tag: 1.31.0-rc.0~1969^2
X-Git-Url: http://git.cyclocoop.org/%24action?a=commitdiff_plain;h=4b42896be44f809912831bcfe660bb9ef97f7c1b;p=lhc%2Fweb%2Fwiklou.git

Update documentation for IApiMessage interface

It was created for a specific purpose, and apparently this is confusing
some people who're inexplicably trying to implement it outside of that
purpose. So, this patch more clearly documents that purpose.

Change-Id: I638482327370522bedea1ec514ecbb9d98207382
---

diff --git a/includes/api/ApiMessage.php b/includes/api/ApiMessage.php
index 9e42d5fd73..3347128757 100644
--- a/includes/api/ApiMessage.php
+++ b/includes/api/ApiMessage.php
@@ -30,6 +30,13 @@
  * (see e.g. Title::getUserPermissionsErrors()) and the API has to make do with that.
  *
  * @since 1.25
+ * @note This interface exists to work around PHP's inheritance, so ApiMessage
+ *  can extend Message and ApiRawMessage can extend RawMessage while still
+ *  allowing an instanceof check for a Message object including this
+ *  functionality. If for some reason you feel the need to implement this
+ *  interface on some other class, that class must also implement all the
+ *  public methods the Message class provides (not just those from
+ *  MessageSpecifier, which as written is fairly useless).
  * @ingroup API
  */
 interface IApiMessage extends MessageSpecifier {