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 -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
