Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:55756
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain sugarcrm.com designates 207.97.245.143 as permitted sender)
Message-ID: <4E908CFC.7030208@sugarcrm.com>
Date: Sat, 08 Oct 2011 19:48:44 +0200
Organization: SugarCRM
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:7.0.1) Gecko/20110929 Thunderbird/7.0.1
MIME-Version: 1.0
To: Hannes Magnusson <hannes.magnusson@gmail.com>
CC: Ferenc Kovacs <tyra3l@gmail.com>, 
 Gustavo Lopes <glopes@nebm.ist.utl.pt>,
 "internals@lists.php.net" <internals@lists.php.net>
References: <4E5B24DD.10903@sugarcrm.com>	<op.v0yn2z06idpuyk@damnation> <4E671355.5060908@sugarcrm.com> <CAH-PCH4JaCrbuQzL+c5M6vYjfNEJXAUktLxmc7w5pfuLqdYiSQ@mail.gmail.com> <CADNQb0WK5sGO0EWRtALz6sM-+eFiat48VpNaEiWu5LNcPGhQcw@mail.gmail.com>
In-Reply-To: <CADNQb0WK5sGO0EWRtALz6sM-+eFiat48VpNaEiWu5LNcPGhQcw@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] 5.4 beta
From: smalyshev@sugarcrm.com (Stas Malyshev)

Hi!

On 10/7/11 8:13 PM, Hannes Magnusson wrote:
> The UPGRADING file is also completely worthless.
> I have no idea what is going on, as a dev, nor as a documentor.
> Be it traits, closures, or whatever random new parameter or function was added.
> When 5.3 came around, I literally had to diff the sources to figure
> out what was going on, I am not going through that again.

I'll check out UPGRADING file, thanks for reminding about it, however I 
do not think UPGRADING is the right place to document language features 
- and, frankly, I didn't hear about the rule that one is supposed to 
update UPGRADING file with each change.

I think stuff should be documented first and foremost in the usual place 
- in the manual and it is the responsibility of whoever adds the feature 
to ensure that it happens. I'll go through new features that are in TODO 
and make a list of which ones aren't properly documented soon.

Right now, for example, as far as I can see Closure is not documented at 
all with regard to which methods it has, and the syntax for anonymous 
functions in general is somewhat learn-by-example - neither static 
closures nor "use" aren't explicitly documented - even though the docs 
mention importing parameters from parent scope, the docs text (as 
opposed to the example) never mentions the "use" keyword is used for 
that. Neither use by-value/by-reference is mentioned.
The issue of scoping is completely avoided and the only note 
tangentially implies you can use $this in the closure but gives no 
explanation about how one would actually use it.

It would be great if we could improve this ASAP in the manual.
-- 
Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227