Experiment: Replace verbose synopses with phpdoc synopsis instruction

[jordikroon]

I have had this thought for a while now and I only recently had the chance to really think of this.

Within the php-src repo, there is a gen_stub.php file that is able to generate XML synopsis from stub files.

We already utilise this generator script to sync stubs from time to time, which works fine. With every new PHP version many stubs change and we need to persist these changes here, and translations need to the same.

So this is a proposal on the implementation side. The code to make this work is surprisingly simple without much overhead. Yes it does require us to pull stub files from php-src (thus another repo dependency), but it will make reviewing easier as we don't need to verify that the stub is correct (or outdated). This does not mean we need to clone the whole repository. Just the stub files, and gen_stub.php is sufficient. And we have the control what branch we target (8.5, 8.6 -> and so on).

I will first check for positive (or negative) feedback before presenting the other side of the code in doc-base. So consider this a small RFC ;-)

[lacatoire]

Nice idea, a single source of truth for synopses would cut a lot of manual syncing, translations included.
I think about 2 things

1. How would pages whose documented signature intentionally differs from the stub be handled (override, or keep the inline <methodsynopsis>)?
2. Which php-src branch or commit would the build pin to, and what happens if the referenced symbol is missing from the stubs? Ideally the build should fail rather than render an empty synopsis.

[jordikroon]

1: Do we have such an example? Drifting away from php-src wouldn't be ideal anyways, unless the stubs have a limitation. Though to answer the question, if that's the case we can and should keep the inline synopsis.

2: Debatable. We could already target 8.6, but it will break existing stubs. Is that ideal? Maybe not at this point, but we are 1 month away from an actual release. So I am not too bothered by it.

An option though would be to support multiple branches, where we look at the minimum target (8.5), and if a stub is not available in that branch that we look at 8.6. That should allow us to write non breaking documentation while 8.6 is still a Release Candidate.

So realistically speaking, I am okay targeting 8.6 directly. And for 8.7, we could bump this version when 8.7 is in RC phase. So we don't have to implement a workaround that is only convenient for single month of the year.