Re: Render function and method signatures using PHP7's format.

Hello W dniu 02.05.2017 o 13:35, Richard Quadling pisze:

Hello Maciej, It would be really nice to fix just the return type hinting. With that in place, PHP is adhering to the suggested PSR-5.

Right, I guess we could start with just return types. Anything else might be added later if that's what we want. I suggest to wait for more opinions and than I can commit what's needed.

The issues around composer need not be involved in that.

Definitely. I wanted to give a background on that branch. However, we still need to make new release of PhD to apply these changes outside docs.php.net and I'd really, really like to get rid of PEAR before it happens. PS: too agressive ML filter strikes again...

On 2 May 2017 at 11:48, Maciej Sobaczewski <sobak@php.net <mailto:sobak@php.net>> wrote:

    Hello Richard,

    I have working implementation for this feature.

    https://github.com/Sobak/phd/commits/php-methodsynopsis
    <https://github.com/Sobak/phd/commits/php-methodsynopsis>

    IIRC, it still has one or two gotchas, but it doesn't require
    any modification in <methodsynopsis> structure (at least on
    functions' pages, not sure about classes overviews).

    Please take a note that is based on a different branch of mine,
    "composer". I hoped it would be merged some time ago, but I'm
    stuck on required changes in servers configuration :/ I'm not
    saying I can't rebase it, though.

    Look at the
    https://github.com/morrisonlevi/web-php/issues/4#issuecomment-267585766
    <https://github.com/morrisonlevi/web-php/issues/4#issuecomment-267585766>
    for more details. Wrt. spacing issue, now I think it should be
    fixable with simple CSS float.

    Cheers,
    Maciej.

    W dniu 02.05.2017 o 12:17, Richard Quadling pisze:

        Hello all.

        Currently, PHD renders method and function signatures with the
        return
        type up front, similar to C and other languages. Prior to PHP 7,
        I'd say
        that there was nothing wrong with this, as there was no PHP code
        equivalent and it's placement was probably discussed at length and
        agreed upon.

        But with PHP7's return type hinting placing the return type at
        the end
        of the signature, we are now in the situation that the first port of
        call for a developer, when reading example function usage, has
        to NOT
        use the general structure from the documentation and place the
        return
        type at the end of the signature for their function and method
        definitions. Whilst return type hinting is relatively new and
        PHP5 still
        has a significant client usage, this won't always be the case and
        eventually everyone will look back and gently wipe away the tear
        as it
        rolls slowly down their cheek at the mention of PHP5.

        I'm trying to get
        https://github.com/php-fig/fig-standards/pull/899
        <https://github.com/php-fig/fig-standards/pull/899>
        (Align PSR-5 @method signatures with PHP7 with regard to return
        types)
        accepted (that's in progress with the current owner of PSR-5).

        In addition to PSR-5, once the standard is accepted, tools like
        PHP-CS,
        PHPStan, PHPDocumentor, will be able to suggest/coerce/enforce
        (pick a
        term you're happy with) this standard.

        But I think if we already have a signature format (PHP 7), then
        PHP's
        own documentation should follow it. And if that's done, all the
        other
        players will (hopefully) fall in place.

        Once PHP and PSR-5 define the standard, it will be some grunt
        work to
        get the major frameworks and libraries updated to the standard.

        In terms of PHP documentation, I'm hoping that amending PHD is the
        solution here and not have to alter the methodsynopsis tags in
        php-doc.
        Though, if that's necessary, a painful but easy task.

        So, thoughts/opinions please.

        Regards,

        Richard Quadling.