Re: PECL/Memcache documentation

Hi Brian, On 17 June 2010 21:34, Brian Moon <brian@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. >