Re: [PHP-DOC] PECL/Memcache documentation

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