Re: 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