Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:113392
To: "G. P. B." <george.banyard@gmail.com>, AllenJB <php.lists@allenjb.me.uk>
Cc: PHP internals <internals@lists.php.net>
References: <CAFPFaMLhUtvygtkgWvDRYZvCc8sFNtVDiUEmAHjuXK+H=aFHbA@mail.gmail.com>
 <2dcc41aa-6518-baf1-5548-de0c41e0a8f3@allenjb.me.uk>
 <CAFPFaMK7Cn0won7GuHo=8QBwM5Qu0=SuFbsjYmRs4GkC-px5pw@mail.gmail.com>
Message-ID: <8e32e4bb-2a0b-8607-c541-ccf2c5ba362a@gmx.de>
Date: Thu, 4 Mar 2021 22:53:35 +0100
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:78.0) Gecko/20100101
 Thunderbird/78.8.0
MIME-Version: 1.0
In-Reply-To: <CAFPFaMK7Cn0won7GuHo=8QBwM5Qu0=SuFbsjYmRs4GkC-px5pw@mail.gmail.com>
Content-Type: text/plain; charset=utf-8
Content-Language: de-DE
Content-Transfer-Encoding: quoted-printable
Subject: Re: [PHP-DEV] [RFC] Extend error control operator to suppress
 exceptions
From: cmbecker69@gmx.de ("Christoph M. Becker")

On 04.03.2021 at 18:46, G. P. B. wrote:

> On Thu, 4 Mar 2021 at 16:06, AllenJB <php.lists@allenjb.me.uk> wrote:
>
>> On a related note I dislike "documentation burden" as an argument
>> against improvements. I obviously understand "open source, volunteers,
>> translations, etc" but I've heard this a few times now as an argument
>> against fixing various issues (another example is that many functions i=
n
>> the manual document that they can return false, but there's absolutely
>> no explanation as to when this can occur except a single paragraph that
>> lives on its own page that nobody is ever likely to find if they don't
>> already know it exists and you can't tell which functions it actually
>> applies to even if you do). Obviously the project doesn't, but if you
>> followed this for everything (to the extreme), you'd never introduce an=
y
>> new functionality because it would mean adding more documentation pages=
.
>> If this is an issue, does the project need to consider if there are
>> better ways to handle documentation?
>>
>
> The matter of fact is that at this time there is mainly 1 person which
> solely
> works on the documentation, and that is Christoph M. Becker (aka cmb)
> with some occasional contribution from other individuals (me included)
> even with an issue tracker we are far from having all the changes for PH=
P 8
> documented, and even some PHP 7 behaviour is not documented.
> So documentation burden is a thing, should it prevent feature additions =
to
> the langage? Obviously not, and we mostly deal with this "just" fine as =
for
> the docs of the major PHP 8 features were written by their respective RF=
C
> authors.
>
> A big reason why there was no documentation for false return in the
> signature is that until recently we did *not* have the capability to dis=
play
> union types via the Doc render (PhD), this is now being corrected but is
> a tedious job of syncing the docs from the officials stubs to also sync
> named arguments.

Allen's point is about the undocumented return values when calling
functions with unexpected parameter types (e.g. calling strlen() on an
object).  There has been quite some discussion about this over the
years, mostly on the docs mailing list, and I still don't think this
should be documented for each function individually, because it is by
definition *undefined* behavior.  If it was defined behavior, we could
not have elevated this to TypeErrors in PHP 8.0 due to the massive BC
break.  The fact that this documentation would take years (assuming the
current bandwidth) is secondary.

Regarding syncing the docs form the official stubs: M=C3=A1t=C3=A9 did a g=
reat job
of semi-automating this, so it isn't *that* much work anymore, but in my
opinion it is important to also keep the documentation correct for PHP
7, and this requires a lot of manual review, and not rarely looking up
the actual behavior from the implementation =E2=80=93 that is quite some w=
ork,
and the reviewer's constant reminder how incomplete and out-dated large
parts of the manual actually are.

=2D-
Christoph M. Becker