- * unless the callback returns false. The arguments supplied to it are:
- * (current value or false, &$ttl, &$setOpts)
- * The callback function returns the new value given the current
- * value (false if not present). Preemptive re-caching and $checkKeys
- * can result in a non-false current value. The TTL of the new value
- * can be set dynamically by altering $ttl in the callback (by reference).
- * The $setOpts array can be altered and is given to set() when called;
- * it is recommended to set the 'since' field to avoid race conditions.
- * Setting 'lag' helps avoids keys getting stuck in long-term stale states.
- *
- * Usually, callbacks ignore the current value, but it can be used
- * to maintain "most recent X" values that come from time or sequence
- * based source data, provided that the "as of" id/time is tracked.
- *
- * Usage of $checkKeys is similar to get() and getMulti(). However,
- * rather than the caller having to inspect a "current time left"
- * variable (e.g. $curTTL, $curTTLs), a cache regeneration will be
- * triggered using the callback.
+ * (unless the callback returns false) and that result will be returned.
+ * The arguments supplied to the callback are:
+ * - $oldValue : current cache value or false if not present
+ * - &$ttl : a reference to the TTL which can be altered
+ * - &$setOpts : a reference to options for set() which can be altered
+ *
+ * It is strongly recommended to set the 'lag' and 'since' fields to avoid race conditions
+ * that can cause stale values to get stuck at keys. Usually, callbacks ignore the current
+ * value, but it can be used to maintain "most recent X" values that come from time or
+ * sequence based source data, provided that the "as of" id/time is tracked. Note that
+ * preemptive regeneration and $checkKeys can result in a non-false current value.
+ *
+ * Usage of $checkKeys is similar to get() and getMulti(). However, rather than the caller
+ * having to inspect a "current time left" variable (e.g. $curTTL, $curTTLs), a cache
+ * regeneration will automatically be triggered using the callback.