Hi Brian,

On 17 June 2010 21:34, Brian Moon <br...@moonspot.net> wrote:
>> 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?
>
> Ok, new patch attached. I can live with documented but deprecated.
>
>> Also,<initializer>  for $timeout should be 0 in the
>> associated<methodparam>.
>
> I didn't touch the methodparam block. So, I am not sure what you are talking
> about.

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.

>
>> 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.

[1] See an example: http://wiki.php.net/doc/skeletons/function

>
> Brian.
>

Reply via email to