[prev in list] [next in list] [prev in thread] [next in thread] 

List:       php-doc-cvs
Subject:    Re: [DOC-CVS] svn: /phpdoc/en/trunk/reference/spl/splfileobject/ tostring.xml
From:       Ferenc Kovacs <tyra3l () gmail ! com>
Date:       2013-01-30 9:37:38
Message-ID: CAH-PCH7tHOJm==vz8gVhu42K3hVEFwdHBzZfQYsSOt-=-Hjkeg () mail ! gmail ! com
[Download RAW message or body]


On Wed, Jan 30, 2013 at 8:48 AM, Peter Cowburn <petercowburn@gmail.com>wrote:

> On 30 January 2013 01:30, Ferenc Kovacs <tyrael@php.net> wrote:
> > tyrael                                   Wed, 30 Jan 2013 01:30:54 +0000
> >
> > Revision: http://svn.php.net/viewvc?view=revision&revision=329366
> >
> > Log:
> > add synopsis for the SplFileObject::__toString method
> >
> > Changed paths:
> >     U   phpdoc/en/trunk/reference/spl/splfileobject/tostring.xml
> >
> > Modified: phpdoc/en/trunk/reference/spl/splfileobject/tostring.xml
> > ===================================================================
> > --- phpdoc/en/trunk/reference/spl/splfileobject/tostring.xml
>  2013-01-30 00:50:20 UTC (rev 329365)
> > +++ phpdoc/en/trunk/reference/spl/splfileobject/tostring.xml
>  2013-01-30 01:30:54 UTC (rev 329366)
> > @@ -9,6 +9,10 @@
> >
> >   <refsect1 role="description">
> >    &reftitle.description;
> > +  <methodsynopsis>
> > +   <modifier>public</modifier>
> <type>void</type><methodname>SplFileObject::__toString</methodname>
> > +   <void />
> > +  </methodsynopsis>
> >    <simpara>
> >     This method is an alias of
> <methodname>SplFileObject::current</methodname>.
> >    </simpara>
> >
>
> We don't have synopses for aliases, only the alias paragraph as
> detailed in the doc howto.
>

hi,

could you please link the relevant page about this?
https://wiki.php.net/doc/skeletons/oo#classnamemethodnamexml is the closest
thing to documenting this behavior but it doesn't contain anything related
to the usage of the alias
<!-- If its a normal method, use this -->
<!-- If this is an property, use this -->
<!-- Note: If this method/property as an alternate procedural mapping then
the method/property synopsis MUST be listed BEFORE the function synopsis -->
my understanding is that the last one is about when we have both a
procedural and an OOP api (mysqli for example), but nothing about aliases
between class methods.

this change was in response to the following mail/bugreport:
http://news.php.net/php.internals/65476
as you can see on http://www.php.net/manual/en/class.splfileobject.php the
__toString method is missing from the Methods synopsis giving the users the
idea, that SplFileObject doesn't have that, so the parents __toString is
inherited, which is false, and they have a different behavior.

Before I commited the change, I looked around, and every other alias under
spl had the method synapsis with the exception of
splfileobject/getcurrentline.xml(which should be also fixed depending on
the outcome of this discussion):

splobjectstorage/offsetunset.xml
splobjectstorage/offsetexists.xml
splobjectstorage/offsetset.xml
splqueue/enqueue.xml
splqueue/dequeue.xml

So I think that the method should be listed in the synopsis (to avoid
confusion), there are existing precedences for aliases between class
methods having methodsynopsis and there is nothing (or at least I couldn't
find)  in the docs related to this, so nothing which would prohibit the
methodsynopsis usage in this case.

What do you think?


-- 
Ferenc Kovács
@Tyr43l - http://tyrael.hu


[prev in list] [next in list] [prev in thread] [next in thread]