Re: svn: /phpdoc/en/trunk/reference/datetime/datetimeimmutable/construct.xml

On 14.08.2015 at 20:57, Adam Harvey wrote: > On 14 August 2015 at 08:18, Peter Cowburn <petercowburn@gmail.com> wrote: >> On 14 August 2015 at 13:49, Christoph Michael Becker <cmb@php.net> wrote: >> >>> cmb Fri, 14 Aug 2015 12:49:32 +0000 >>> >>> Revision: >>> http://svn.php.net/viewvc?view=revision&revision=337451 >>> >>> Log: >>> fixed wrong parameter name (Reflection!) (fixes #70265) >>> >> >> I'd *much* rather see this changed in php-src so that reflection gives a >> more useful name. Changing the parameter name from "timezone" to >> "object" >> is a step backwards. > > Agreed. > > Also, I don't believe we're under any obligation to match parameter > names returned by reflection. It's obviously better if that's the > case, but we have other functions where the documentation has better > parameter names than php-src does, and I don't think anyone's > complained before this bug. > > Of course, if we ever get keyword arguments... :) Okay, I've reverted the commit and re-opened the bug report. Nonetheless, IMHO, consistency is more important than good parameter names, even though that's related to reflection only, currently. For instance, there might be a tool that uses reflection to get the parameter names and automatically constructs deep links to the documentation. And frankly, while object is most certainly an unlucky choice for the name of the parameter in this case, timezone is not perfect either, because as far as I remember there are other functions with parameters with this name, expecting a timezone string. I presume, that was the reason for choosing object in the first place. All in all, I hope we can match the parameter names used for reflection and in the docs in the not too distant future, not only for the English docs, but also in the translations. -- Christoph M. Becker