On Jun 24, 2010, at 9:30 AM, Brian Moon wrote:

>> The default $timeout sent over to memcached, if none was specified, is
>> zero (is it?). If that is the case, the docs need to reflect that
>> (even if the value isn't/shouldn't ever be used) with something like
>> ``...<parameter>timeout</parameter><initializer>0</initializer></methodparam>``
>> -- of course, if there is no default value, then there is no need for
>> an initializer element.
> 
> So, just to confirm, the existing docs are wrong and you need to me to fix 
> them before any other changes can be made? That sounds curt, not meant to be. 
> Just want to understand what needs to happen to get this done.

We're confirming current [and past] behaviour in order to document it as such, 
with the idea being that it should be documented with how it truly behaves, and 
if it ever changes in the future (which it sounds like it will) then we can 
update the docs and the associated changelog entries.

Summary: The manual is for users who have all sorts of memcached and 
pecl/memcache versions, and should allow them to program for all environments.

>>>> And lastly, changes in behavour should be described in the<changelog>
>>>> role within the methods docs.
>>> 
>>> And here you really lost me. I have not done PHP doc work in 10 years so
>>> bear with me. I am sure if you work on them every day this makes sense, but
>>> it reads like Java to me. ;)
>> 
>> Presumably, the $timeout parameter worked at some point? The
>> changeover from being accepted to being deprecated/unsupported needs
>> to be documented in a "Changelog" block[1] so that folks using an old
>> version (god forbid) can see how things were rather than how things
>> are.
> 
> No, it never worked. The extension was wrong wrong wrong always. It lied to 
> the user about what the timeout did. Yes, memcached took the parameter in the 
> past, but never with the behavior that was documented here. But, I will do 
> whatever it takes to get these docs updated.

Okay that's good to know, I also wasn't sure if it worked or not or ever did 
anything in the past. And after all is said and done, do you have a new patch 
that adheres to the above goals? You sound like you know more about this topic 
than anyone else on the planet :)

Regards,
Philip

Reply via email to