Re: STH Docs.

On Wed, Apr 29, 2015 at 7:04 AM, Peter Cowburn <petercowburn@gmail.com> wrote: > > > On 27 April 2015 at 19:53, Rowan Collins <rowan.collins@gmail.com> wrote: >> >> Pasindu De Silva wrote on 27/04/2015 04:37: >>> >>> Hi Guys >>> I am doing some documentation for STH but not sure where to put it. >>> Current type hintings are under oop5 >>> (http://php.net/manual/en/language.oop5.typehinting.php). >>> So should we make something called oop7 and put STH under that or else >>> under oop5. >> >> >> Technically, the new type hinting features have nothing to do with OOP, >> since the whole point is that we're hinting types other than objects. >> (Arguably, that was already true of "array" and "callable", added in >> 5.1 and >> 5.4, respectively.) > > > We should definitely have a page/section about hinting for function > parameters, out-with the oop5 section... that is a long overdue change. > >> >> >> I would have thought the page should be moved into either the "Types" >> chapter [1] (which covers Type Juggling) or the "Functions" chapter [2] >> (which covers things like default and variable-length argument lists), with >> a clear note about which parts are new to PHP 7. > > > The "functions" chapter should detail parameter and return type hinting; > either in a "type hinting" section, and/or by mentioning them in the > existing "function arguments" and "returning values" sections. This is a good approach. I think I can write a draft of the reworked pages sometime in the next week. To clarify something else: I don't think combing the documentation to remove references to "type hint" is effort well spent. Rather what I meant was that in any new documentation, or if we alter an exiting section, we should choose a more correct terminology. Some phrases that work in various contexts: - explicit type: Argument $foo has an explicit type of Foo. - type declaration: Argument $foo has a type declaration of Foo. - parameter type: The parameter type of function foo is Foo. - return type: The return type of function foo is Foo.