Re: Changing our function definition syntax in the manual

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 >