Re: Changing our function definition syntax in the manual

I think we need to start thinking about splitting the prototypes into two types: - Suggested return type, suggested argument types (more or less our current syntax) And, as the language as evolved over the years: - Type hinted argument types, type hinted return types ("PHP 7 compatible syntax") These mean two different thing when it comes to error handling so I do think its important that we differentiate these two. If a function has been "upgraded" to become type hinted in later versions then we should include multiple prototypes for it, with version specific caveats. Docbook allows for multiple methodsynopsis, so all we have to do is annotate them with role="typed" role="suggested" and stick a changelog entry "as of PHP 7 this function is type hinted" for upgraded functions. It shouldn't be all that complicated to do this in PhD, and I guess there are some minor css changes needed following that change. -Hannes On Tue, Nov 10, 2015 at 2:43 PM, Julien Pauli <jpauli@php.net> wrote: > On Tue, Nov 10, 2015 at 11:04 PM, Levi Morrison <levim@php.net> wrote: >> I am talking about the PHD rendering system, yes (though not >> necessarily the file/commit you linked). >> >> To clarify, the XML for strpos looks like this: >> >> <methodsynopsis> >> <type>mixed</type><methodname>strpos</methodname> >> >> <methodparam><type>string</type><parameter>haystack</parameter></methodparam> >> >> <methodparam><type>mixed</type><parameter>needle</parameter></methodparam> >> <methodparam >> >> choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam> >> </methodsynopsis> >> >> The XML does not need to change; in fact the schema doesn't allow for >> a trailing return type[1]. Instead we need to change how we render the >> XML to put the return type at the end. >> >> The difficulty in this is that the renderer is essentially rendering >> things recursively; I'm not familiar enough with the system to >> identify a methodsynopsis and to render it and its children in some >> other way and preventing it from recursing. >> >> Does that make sense? >> >> [1]: ¢8G°g Ö >> ºÒ–J,http://www.docbook.org/tdg/en/html/methodsynopsis.html >> >> >> On Tue, Nov 10, 2015 at 2:57 PM, Sherif Ramadan <theanomaly.is@gmail.com> wrote: >>> Levi, >>> >>> Are you referring to >>> >>> http://git.php.net/?p=phd.git;a=blob;f=phpdotnet/phd/Format/Abstract/XHTML.php;h=6232cfc288c9d92fd537312ecd6bbf65e37144e9;hb=HEAD >>> ? >>> >>> On Tue, Nov 10, 2015 at 4:38 PM, Levi Morrison <levim@php.net> wrote: >>>> >>>> You don't need to change the XML, just the renderer. This is much >>>> easier than changing the sources but still would take a bit of time to >>>> figure out the proper way to do with our renderer. I looked into doing >>>> it myself but then I got busy with life. >>>> >>>> On Tue, Nov 10, 2015 at 2:23 PM, Sherif Ramadan <theanomaly.is@gmail.com> >>>> wrote: >>>> > Also, I dislike the idea of having inconsistent formats in the >>>> > prototypes >>>> > across functions. There are a handful of PHP 7 specific functions. Why >>>> > have >>>> > disparity? It only serves to irritate people in the log run on where to >>>> > look >>>> > for return types in the rototype header. >>>> > >>>> > If we do a mass change across the board for all functions I have to >>>> > agree >>>> > with Adam's assessment that it's not so trivial with the CSS we >>>> > currently >>>> > have. >>>> > >>>> > You have to change the DTD as well as the XML in all of the >>>> > function/method >>>> > pages. There's also the CHM builds which I know nothing about and then >>>> > yea, >>>> > translations. That's potentially hundreds of thousands of files changed. >>>> > >>>> > Seems like a lot of work for merely moving a return type from the left >>>> > of >>>> > the prototype to its right. And the net gain is merely being consistent >>>> > with >>>> > language syntax? The docs have never really been consistent there >>>> > anyway. We >>>> > still have missing visibility specifiers in some method signatures if I >>>> > recall correctly. I'd say those are more worth while fixing first. >>>> > >>>> > >>>> > >>>> > On Tue, Nov 10, 2015 at 3:47 PM, Adam Harvey <aharvey@php.net> wrote: >>>> >> >>>> >> On 10 November 2015 at 12:19, Julien Pauli <jpauli@php.net> wrote: >>>> >> > The twitt (https://twitter.com/tvlooy/status/664109119343878144) was >>>> >> > about why don't we show function syntax for description using >>>> >> > the new >>>> >> > declaration syntax used in PHP 7 parser ? >>>> >> >>>> >> I had this on my list of things to look at when I was on my migration >>>> >> guide tear a couple of months back, but then totally forgot. >>>> >> >>>> >> I think it'd be a nice to have, but I don't see a great option >>>> >> for >>>> >> implementing it. Doing it purely in CSS would be ideal, but the markup >>>> >> we currently generate doesn't really allow for that: you can't >>>> >> float >>>> >> the return type right because the container is full width, and using >>>> >> flexbox to reorder causes unfixable spacing issues due to the fact we >>>> >> have inline text (for things like the parentheses around parameters) >>>> >> that we can't add padding to (since switching .methodsynopsis to >>>> >> display: flex collapses all the whitespace within it, which is >>>> >> important for formatting). >>>> >> >>>> >> It feels like the only viable options are: >>>> >> >>>> >> 1. Changing PhD to emit another, semantically unimportant element >>>> >> inside .methodsynopsis that we can style as an inline-block, then >>>> >> float the return type right. >>>> >> >>>> >> 2. Changing every function/method page in the manual to reorder where >>>> >> the return type appears, then have PhD insert the colon in the right >>>> >> place. >>>> >> >>>> >> I don't really love either. I dislike option 2 more than option 1; it >>>> >> feels like a lot of churn for little benefit, and all translations >>>> >> would have to make the same mechanical change. (Presumably it could be >>>> >> mostly scripted, but it's still a pain.) >>>> >> >>>> >> All that said, since I've been out of the Web development game for a >>>> >> while now: what am I missing? >>>> >> >>>> >> Adam >>>> > >>>> > >>> >>> > > I would say that it was just a suggestion, if some minds are against, > or if it's technically not trivial to implement, > let's forget about it. (I thought it'd be easier :-p ). > > > Julien.Pauli