Re: Reformat method synopsis whitespaces

On 01.06.2021 at 18:14, Máté Kocsis wrote:

> I'm looking for feedback with regard to my PR which reformats method
> synopses (https://github.com/php/phd/pull/38):
>
> Currently, we display function/method signatures without any line breaks,
> but with a lot of unnecessary spaces between parameters, as well as around
> the parameter list. See an example here: https://pasteboard.co/K4BXRuv.png
>
> My PR would add a line break for each parameter as well as remove any other
> unnecessary whitespaces. See https://pasteboard.co/K4BZNN9.png for example
> (but the linked PR has a few more images attached).
>
> I'm curious if anybody sees any issue with the new formatting? Class
> synopses look a bit weird, but I don't think it's worse than what we
> currently have.

Thank you, Máté, I love it!  Finally, the signatures look like code you
may find in a PHP code base.  That's a nice progress within less than
three years, where the manual even resorted to pseudo-syntax[1].

I agree that the new formatting of class synopses may need some time to
get used to, and sometimes a lot of scrolling, but that may hint at
classes with too many methods[2], and there are other means to get an
overview of all methods of a class anyway.

CCing Philip, who may have thoughts on this as well.

[1]
<https://web.archive.org/web/20180731100347/http://php.net/manual/en/function.printf.php>
[2]
<https://web.archive.org/web/20180731100347/http://php.net/manual/en/function.printf.php>

--
Christoph M. Becker