Re: svn: /phpdoc/en/trunk/reference/datetime/datetimeimmutable/construct.xml
| From: | Peter Cowburn | Date: | Fri, 14 Aug 2015 21:51:14 +0000 |
| Subject: | Re: svn: /phpdoc/en/trunk/reference/datetime/datetimeimmutable/construct.xml | ||
| References: | 1 2 3 4 | Groups: | php.doc.cvs |
| Request: | Send a blank email to doc-cvs+get-13579@lists.php.net to get a copy of this message | ||
On 14 August 2015 at 22:34, Christoph Becker <cmbecker69@gmx.de> wrote:
> 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,
Having both, is best.
> 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.
>
In the past, several times we have changed php-src to reflect (pardon the
pun) better/more appropriate/different argument names that were being used
in the manual. This would certainly not be a first.
I think that "timezone" is fine, and if anything at all should be done it's
changing arginfo to the same.
>
> --
> Christoph M. Becker
>