On Jun 17, 2010, at 11:49 AM, Brian Moon wrote:

> I have been asked by the memcached maintainers to help facilitate a change in 
> the pecl/memcache library since I have a PHP SVN account. However, I don't 
> think I have karma on the pecl extension or the docs.
> 
> The delete() function is currently documented as taking a timeout parameter. 
> 2.2.5 does in fact send the timeout parameter. There are a couple of problems 
> with that.
> 
> 1. The documented behavior is inaccurate. The timeout actually blocked 
> operations on the key. It did not delete it after the given time.
> 
> 2. Since 1.4.0, memcached has only accepted a 0 for the timeout. And that is 
> only so that pecl/memcache would work for those people that did not try and 
> send the timeout. Some version was sending 1 by default. That was fixed at 
> some point.
> 
> So, I would like to request an immediate change to the docs based on the 
> attached patch. And then I can work on patching the code and submitting that 
> as well. But the sooner we get that behavior out of the documentation the 
> better. It is a constant question on the IRC channel, mailing list and in 
> person at conferences.

Hello Brian,

The patch deletes the timeout parameter from the parameters documentation, yet 
the parameter exists in the function signature. Regardless of how useful a 
parameter is, the documentation should match the signature/behaviour which 
means leaving it (but changing its description). Right?

Also, <initializer> for $timeout should be 0 in the associated <methodparam>.

And lastly, changes in behavour should be described in the <changelog> role 
within the methods docs.

Regards,
Philip

Reply via email to