On 04.03.2021 at 18:46, G. P. B. wrote: > On Thu, 4 Mar 2021 at 16:06, AllenJB <php.li...@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 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 any >> 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 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 RFC > 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 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áté 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 – 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 -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: https://www.php.net/unsub.php
