dom: Add stubs generated from php-src stubs

[Girgias]

Generate using php/php-src#12330 and running the following command (for my folder hierarchy):

../php-src/build/gen_stub.php --generate-methodsynopses ../PHP-8.3/ext/dom/ ../docs-php/en/reference/dom/

[kocsismate]

Wouldn't it be better to leave these empty instead?

[Girgias]

Well, ideally, people would work on them directly after generating the stubs. And if no text is generated, one gets an empty tag, which I don't think is great.

[ndossche]

A question.
The after() method on DOMElement etc come from the interface DOMChildNode. Looking at that page I see after() listed there: https://www.php.net/manual/en/class.domchildnode.php
Clicking on after() reveals its documentation, albeit a bit lackluster. It's also hard to discover these methods right now.

The after() method (and others coming from the interface) is not listed on https://www.php.net/manual/en/class.domelement.php
So how do we go about it? I guess the description should be the same for all of them. It's a bit weird that the interface has a page tbh?

[Girgias]

Oh so that's where they are documented.

I mean one solution is to add:

    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.domparentnode')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='DOMParentNode'])">
     <xi:fallback/>
    </xi:include>

In the inherited method section, maybe having a look at how countable classes do it? As Countable::count also has a page

[TimWolla]

It's also hard to discover these methods right now.

Indeed. I've ran into this exact issue myself before: https://chat.stackoverflow.com/transcript/message/56491752#56491752

[ndossche]

These still remain and I'll try to finish them soon:

• replaceWith
• replaceChildren
• getIterator

Thanks for having a look already

[ndossche]

Looks like I'm getting some errors because of the xincludes:

File /home/runner/work/doc-en/doc-en/en/reference/dom/domcharacterdata/after.xml No parameters sections.
File /home/runner/work/doc-en/doc-en/en/reference/dom/domcharacterdata/after.xml No returnvalues sections.

are those checked before resolving the xincludes by any chance?

[Girgias]

Looks like I'm getting some errors because of the xincludes:

File /home/runner/work/doc-en/doc-en/en/reference/dom/domcharacterdata/after.xml No parameters sections.
File /home/runner/work/doc-en/doc-en/en/reference/dom/domcharacterdata/after.xml No returnvalues sections.

are those checked before resolving the xincludes by any chance?

Yes, they don't actually work on the manual but individual files. Just go and add exceptions to the sections_check QA script. As it probably should be written to work on the full manual.

[ndossche]

I think this is ready for review now.
I submitted php/doc-base#106 to fix the integration.

[Girgias]

LGTM except the formatting of the error sections which I am not sure.

variablelist feels inappropriate, I usually think if doing it that way we use itemizedlist but DocBook seems to be OK with using it that way.

Now the wrapping para tag is unnecessary and should be removed.

The last thin is that it would be nice to have the descriptions for the errors somehow only written once and included so that they don't go out of sync.

[Girgias]

This might make sense to either use an entity in language snippets, or possibly add a file to XInclude with an URL to a local file? (maybe for translations one want's a fallback that traverses up to directory structure then go down with ../en/reference/dom/

[TimWolla]

For ext/random, I have this:

doc-en/reference/random/random/randomizer/getint.xml

Line 64 in 32c8df6

&random.engineErrors;

[ndossche]

Fixed via entity

[Girgias]

LGTM! Thank you!