fix official doc?

[orklah]

Do you think this could be used to fix official documentation from stubs? Now that the doc is on github, it could be a great opportunity to fix errors directly in the source

[voku]

@orklah I already created a small pull request (to see if this is wanted at all) here: php/doc-en#189

They wanted to discuss via phpdoc@lists.php.net but I didn't start the discussion because I never discussed via mailing-lists and didn't know where to start or that to write there ❓

[orklah]

Oh nice, I had missed that!

Well for me there's at least three issues:

• Factual errors with current syntax
  I saw a few times PR submitted in Psalm where php.net was simply incorrect or inaccurate. For example missing a part of the union or something like that. This item should be fixed at least partially by internal stubs that were made on PHP8, but I don't think all extensions were concerned. Your tool could maybe be used to find those cases and submit them while keeping current syntax (not detailing array shapes and pseudo types for example)
• approved phpdoc syntax
  This is the item where a discussion could be helpful. Phpdoc standards are now pretty established so it shouldn't be an obstacle in theory: even if it's not directly in the signature block, there should be a special block to display the phpdoc compatible way to describe array shapes (i.e. int[], (int|string)[] ...)
• special keywords and generics syntax
  I think this one will be hard to pass, and I'm not sure we want that. For example list<int> has no actual meaning in php core. Using this syntax on documentation would potentially obstruct future RFC that would want to introduce a list keyword slightly different. The same goes for all keyword not part of the language (i.e. things like class-string). Generics are also hard to pass. They could imply the language support them and confuse readers coming from other languages as to what will be returned exactly.