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

Hi Richard,

Is it possible to get this moving? Ideally, if we can get the function and method signatures obeying the PHP7 syntax, that would be great.

Of course. Let's put PEAR -> Composer migration aside for now, as it's apparently stuck and there's nothing I can do to push it alone. If noone oposes, I'll try to manage whole release process for the new PhD version (I know PhD doesn't have formalised RM etc, but a bit of coordination would be helpful, IMO). Let me gather feedback on proposed signatures change, rebase my branch and fix very few outstanding issues. Then, I would release PhD 1.1.11, so that it will become stable version so PHP.net across the globe will make use of it, and not only docs.php.net Anything else coming to your mind? Cheers, Maciej.

Regards, Richard. On 2 May 2017 at 12:40, Maciej Sobaczewski <sobak@php.net <mailto:sobak@php.net>> wrote:

    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 <http://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>
        <mailto: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>
            <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>

        <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>
                <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.

-- Richard Quadling