Generate docbook methodsynopses from stubs

[cmb69]

Since the docgen tool for generating (new) documentation of classes and functions relies on Reflection, it might actually be interesting to generate the docbook <methodsynopsis> elements from the stubs directly, to have access to the useful docblock comments.

This draft is a quick hack to explore this possibility. The code should actually not go into php-src, but rather into doc-base. Also, a lot of very relevant stuff is missing:

• have a separate script for this (requires some of the classes, though)
• process multiple/all stub files in one go?
• generate separate files or even fix docs right away?
• use XMLWriter instead of DOM?
• support modifiers for methods (visibility, static etc.)
• use docblock info regarding params and types (and maybe more)
• support aliases

Anyhow, even with improvements, the task of getting the PHP manual up-to-date wrt. the function and method signatures appears to be huge due to the sheer amount of functions (currently 542 in basic_functions.stub.php, only).

[kocsismate]

The code should actually not go into php-src, but rather into doc-base.

What's the reason you think so? For me, putting it into php-src sounds like a better option, since generating signatures for the manual is tightly coupled to gen_stub.php, so from a maintainenance point of view, it'd be much easier to keep these functionalities close to each other.

process multiple/all stub files in one go?

We could use a @generate-function-synopsyses file-level annotation in the stub files to enable generation of synopsyses (similar to @generate-function-entries). Besides this, supporting a path argument (which gen_stub.php already allows) is a good idea.

generate separate files or even fix docs right away?

I think the end-goal should be to fully automatically generate these entries (even though it might be impossible for now), so I'd say that generating standalone files that can be referenced in the corresponding xml file seems a good idea for me. This way, generated code could be kept away from manually maintained code. Additionally, it would also have the benefit that we are free not to include synopsyses that are not entirely correct yet.

use docblock info regarding params and types (and maybe more)

I think if there's no native type declared, we should first fallback to PHPDoc (and then to mixed). There are a couple of cases where both a native type declaration (e.g. mixed) and a PHPDoc type hint are available (as a clarification). In this case, I think we should just stay with the type declaration.

support aliases

I noticed that the manual also reports methods as aliases which implement an interface method (e.g. https://www.php.net/manual/en/datetime.diff). Another gotcha is that a few methods are marked with @alias, even though they don't have a real alias, rather they just share a common implementation with another method (e.g. ReflectionProperty::__clone() and ReflectionClass::__clone()). Also, aliased functions might not even be exposed to user-land (I can't find an example now, but there used to be at least one such function until I removed it :) ).

A question from me: Would it be possible to reference parameter names in descriptions based on synopsyses? So that we don't have to hard-code their names in multiple places.

[cmb69]

Thanks for the feedback, @kocsismate! I'll have to think about it. I like the idea of finally having separate files which are just referenced from the manual – that could also be very helpful for the translations.

Would it be possible to reference parameter names in descriptions based on synopsyses? So that we don't have to hard-code their names in multiple places.

We coud define respective XML entities, and reference them in the manual. That appears to be reasonable, although details need to be figured out (not sure if PhD would need to be adapted also).

[kocsismate]

It's soon time to get back to this PR. :) That said, I'll happily take this task over, given you want to get free from it. :)

However, I think we should find out what to do with #6289 with regards to this one. Currently, my PR is targeted for PHP 8.1 (which is ok), but if we also want to merge this PR into PHP 8.0 then we possibly have a big problem... :) Unless we really don't want to use gen_stubs.php for generating methodsynopses, of course. But to be honest, it doesn't seem a realistic scenario.

There's a couple of possibilities how to integrate these and my changes but I'd be curious about your and @nikic's opinion (e.g. we could merge both to master only, or merge both to PHP 8.0 without generating any class initialization code). What is your stance?

@cmb69 Is there any remaining issue with phd that should be solved before generating these XMLs? I remember that Nikita was happy about some progress (was it union types?), but I can image there are other issues as well. :) And of course, we should soon decide about the questions that were originally posed, so I'm looking forward to your ideas as soon as you have time to think about them.

[cmb69]

I'd be very glad if you could take over this task. :)

I'm still not convinced that we should use gen_stubs.php, but I'm certainly not against it. I don't see a big issue for adding functionality to gen_stubs.php even after 8.0 GA as long as it doesn't break BC. And, if need be, we could still fork/branch the script temporarily.

Wrt. PhD, there are still show-stoppers: while I made some progress on union types (there is now php/doc-en#151 which should help to test/evaluate changes to PhD), php/phd#30 is still work in progress. And we also want proper support for variadics (php/phd#28 or php/phd#29 or some other solution). I'm hoping to find some time for these tasks soon.

[cmb69]

Closing in favor of PR #6367.