Document inconsistent function signature.

diff --git a/CRM/Utils/Token.php b/CRM/Utils/Token.php
index c40c0da6ab113a6dbb0a09bcedb8258baec67f7e..a23e9f3313d18f60059d68f0411613b5c1d0c819 100644 (file)
--- 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