PHP is documentation done right because of the comments, essentially "Stack Overflow" for PHP before stackoverflow.com was a thing.
I've found an example of documentation done wrong recently with Microsoft .NET 6.0. Apparently, Microsoft has decided that code samples are no longer important
It's funny really, for a programming language to rely on comments made by random people, instead of having those aspects covered in the documentation itself. Shows a bit of lack of care. It seems half-assed as many things in the ecosystem seem. What happens, if they ever lose that database of comments? The whole world scratches their heads wondering how to use standard library functions? Ridiculous. I hope they have good backups.
> I've found an example of documentation done wrong recently with Microsoft .NET 6.0. Apparently, Microsoft has decided that code samples are no longer important
And for as long as important documentation resides in comments in PHP docs, the same can happen to PHP docs. Lets say they push out PHP 9 and some things change. Someone thinks "Ah those comments are not actually true any longer. Lets get rid of them." Bam, massive resource lost, because the knowledge has not been integrated into the documentation.
Assuming they backup the website, how's it going to get lost?