From: Chris Burgess <chris@giantrobot.co.nz>
Date: Thu, 15 Dec 2016 00:11:41 +0000 (+1300)
Subject: Document inconsistent function signature.
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=206f019872ee73b1f738e8e65ebe927c4838122a;p=civicrm-core.git

Document inconsistent function signature.
---

diff --git a/CRM/Utils/Token.php b/CRM/Utils/Token.php
index c40c0da6ab..a23e9f3313 100644
--- a/CRM/Utils/Token.php
+++ b/CRM/Utils/Token.php
@@ -1418,6 +1418,15 @@ class CRM_Utils_Token {
   /**
    * Replace existing greeting tokens in message/subject.
    *
+   * This function operates by reference, modifying the first parameter. Other
+   * methods for token replacement in this class return the modified string.
+   * This leads to inconsistency in how these methods must be applied.
+   *
+   * @TODO Remove that inconsistency in usage.
+   *
+   * ::replaceContactTokens() may need to be called after this method, to
+   * replace tokens supplied from this method.
+   *
    * @param string $tokenString
    * @param array $contactDetails
    * @param int $contactId