Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:113394
MIME-Version: 1.0
References: <CAFPFaMLhUtvygtkgWvDRYZvCc8sFNtVDiUEmAHjuXK+H=aFHbA@mail.gmail.com>
 <2dcc41aa-6518-baf1-5548-de0c41e0a8f3@allenjb.me.uk> <CAFPFaMK7Cn0won7GuHo=8QBwM5Qu0=SuFbsjYmRs4GkC-px5pw@mail.gmail.com>
 <8e32e4bb-2a0b-8607-c541-ccf2c5ba362a@gmx.de>
In-Reply-To: <8e32e4bb-2a0b-8607-c541-ccf2c5ba362a@gmx.de>
Date: Thu, 4 Mar 2021 22:11:03 +0000
Message-ID: <CAFPFaMJkmCs+V+tq1JLyuSmyBfeaLOh9psgkwPshYQ2oumkzdw@mail.gmail.com>
To: "Christoph M. Becker" <cmbecker69@gmx.de>
Cc: AllenJB <php.lists@allenjb.me.uk>, PHP internals <internals@lists.php.net>
Content-Type: multipart/alternative; boundary="000000000000eace9505bcbd3e3f"
Subject: Re: [PHP-DEV] [RFC] Extend error control operator to suppress exceptions
From: george.banyard@gmail.com ("G. P. B.")

--000000000000eace9505bcbd3e3f
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Thu, 4 Mar 2021 at 21:53, Christoph M. Becker <cmbecker69@gmx.de> wrote:

> 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 =
in
> >> the manual document that they can return false, but there's absolutely
> >> no explanation as to when this can occur except a single paragraph tha=
t
> >> 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 a=
ny
> >> new functionality because it would mean adding more documentation page=
s.
> >> 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
> PHP 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 R=
FC
> > 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
> display
> > union types via the Doc render (PhD), this is now being corrected but i=
s
> > 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.
>

Ah right, yeah I don't think those should be documented as it is UB, and
iirc it usually throws an E_WARNING with a null return that's why I got
confused by the usage of "false return", apologies.


> Regarding syncing the docs form the official stubs: M=C3=A1t=C3=A9 did a =
great 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 =
work,
> and the reviewer's constant reminder how incomplete and out-dated large
> parts of the manual actually are.
>

> --
> Christoph M. Becker
>

Yes agreed, and I know Mat=C3=A9 and you have been working on this a lot,
keeping up the French translation up to date with those changes is
challenging at times because it's not just the function signature change
but there are various amendments to the documentation as a whole.
Yesterday I worked on updating the OpenSSL docs and it took me
about 3h30 to perform the syncing process.

George P. Banyard

--000000000000eace9505bcbd3e3f--