[WIP] 8.4: Document all new DOM classes and methods #4212

nielsdos · 2024-12-01T13:18:41Z

Very WIP, not ready for review yet.

TODO:

nielsdos · 2024-12-01T20:58:24Z

@Girgias I've finished with some basics. Most notably the class synopses are generated and the properties etc are all filled in. I've used xinclude quite a bit. I also fixed up some of the old DOM class descriptions.
It's probably best to already review this as-is, even though it's not finished and most notably the methods are missing.
This won't compile out of the box because of the entities.whatever.xml files not being generated because I haven't filled in the method stuff yet, but here's a zip that you can extract in reference/dom/dom to make it build:
entities.dom.zip
You also need php/doc-base#193

Girgias

Didn't test locally but this a pass across the whole PR

Girgias · 2024-12-02T13:29:26Z

reference/dom/constants.xml

     <row xml:id="constant.domstring-size-err">
      <entry>
-       <constant>DOMSTRING_SIZE_ERR</constant>
+       <constant>DOMSTRING_SIZE_ERR</constant> / <constant>Dom\STRING_SIZE_ERR</constant>


The issue I can see for this, is that automatic linking for <constant>Dom\STRING_SIZE_ERR</constant> is not going to work because the row has no corresponding XML ID.

Can an XML element have 2 IDs? If yes that would fix it.

Can an XML element have 2 IDs? If yes that would fix it.

No, but I don't think this is ever linked to directly 🤔

reference/dom/dom/dom-attr.xml

reference/dom/dom/dom-document.xml

reference/dom/domcomment.xml

reference/dom/domdocument.xml

reference/dom/domdocumenttype.xml

reference/dom/domentity.xml

reference/xsl/xsltprocessor/transformtoxml.xml

nielsdos · 2024-12-02T18:57:20Z

Thanks for the initial review. I pushed fixup commits so they can be validated individually, I'll later rebase this to merge the fixups with the original commits.

Girgias · 2024-12-02T19:33:43Z

reference/dom/dom/dom-entity.xml

@@ -7,7 +7,7 @@
 <partintro>
  <section xml:id="dom-entity.intro">
   &reftitle.intro;
-   <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('domentity.intro')/db:simpara)">
+   <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('domentity.intro')/db:para)">


Why not just Xinclude the whole introduction section instead of just including the para? (same for some of the other pages)

Girgias · 2024-12-03T22:06:58Z

reference/dom/dom/dom-comment.xml

+   <para>
+    <simplelist>
+     <member><link xlink:href="&url.spec.dom.living.comment;">WHATWG specification of Comment</link></member>
+    </simplelist>
+   </para>


No need for the wrapping para tag here (haven't checked all of the files, but it might be in others?)

Girgias · 2024-12-03T22:07:28Z

reference/dom/dom/dom-text.xml

+   <para>
+    The <classname>Dom\Text</classname> class inherits from
+    <classname>Dom\CharacterData</classname> and represents a text node.
+   </para>


New file, so <simpara>

Girgias · 2024-12-03T22:10:37Z

reference/dom/dom/attr/isid.xml

+   According to the DOM standard this requires a DTD which defines the
+   attribute ID to be of type ID. You need to validate your document by
+   passing <constant>LIBXML_DTDVALID</constant> to the parse method.


Personalization is used here.

Girgias · 2024-12-03T22:11:21Z

reference/dom/dom/attr/rename.xml

+   <simpara>
+    It is sometimes necessary to change
+    the qualified name and namespace <acronym>URI</acronym> together in one
+    step to not break any namespace rules.
+   </simpara>


The splitting of the line here is a bit strange

Girgias · 2024-12-03T22:12:37Z

reference/dom/dom/characterdata/before.xml

+   <para>
+    Adds nodes before the character data.
+   </para>


Girgias · 2024-12-03T22:12:52Z

reference/dom/dom/characterdata/remove.xml

+   <para>
+    Removes the character data.
+   </para>


Girgias · 2024-12-03T22:13:06Z

reference/dom/dom/characterdata/replacewith.xml

+   <para>
+    Replaces the character data with new nodes.
+   </para>


Girgias · 2024-12-03T22:15:26Z

reference/dom/dom/attr/rename.xml

+  <para>
+   &return.void;
+  </para>
+ </refsect1>


Girgias · 2024-12-03T22:22:40Z

reference/dom/dom/parentnode/queryselector.xml

+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>selectors</parameter></term>
+     <listitem>
+      <simpara>
+       A string containing one or more CSS selectors.
+      </simpara>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>


nielsdos force-pushed the dom-84 branch 2 times, most recently from b40772e to 6b116fb Compare December 1, 2024 15:49

nielsdos mentioned this pull request Dec 1, 2024

PHP 8.4 documentation tracker #3872

Open

nielsdos added this to the PHP 8.4 milestone Dec 1, 2024

nielsdos force-pushed the dom-84 branch 11 times, most recently from 5b1b19a to f762c1a Compare December 1, 2024 20:55

KentarouTakeda mentioned this pull request Dec 2, 2024

PHP 8.4 マニュアル翻訳状況 php/doc-ja#150

Open

Girgias reviewed Dec 2, 2024

View reviewed changes

nielsdos force-pushed the dom-84 branch from e95dca4 to c35be53 Compare December 2, 2024 20:19

nielsdos changed the title ~~[WIP] 8.4: Document all new DOM classes~~ [WIP] 8.4: Document all new DOM classes and methods Dec 2, 2024

nielsdos force-pushed the dom-84 branch from 543dfa5 to 5011b8a Compare December 2, 2024 20:47

nielsdos added 7 commits December 3, 2024 21:15

Reference new Dom class from XSL

c74a882

Reference new Dom class in SimpleXML

a69cf05

Document Dom\import_simplexml

03f7280

Remove unused version entries from dom/versions.xml

4e73a2f

Fix reference to non-existent class

1c59bfd

Update Dom constants for Dom namespace

82092d3

Document Dom\Exception alias

cee1d55

nielsdos added 15 commits December 3, 2024 21:15

Document Dom\EntityReference class

3ab4e97

Document Dom\ProcessingInstruction class

7e82ca7

Document Dom\Document class

4bf2d82

Document Dom\DtdNamedNodeMap class

b823942

Document Dom\Element class

1529189

Document Dom\HTMLCollection class

c1ad5ce

Document Dom\NamedNodeMap class

3a2b7cb

Document Dom\HTMLDocument class

a7d8b81

Document Dom\HTMLElement class

47edaa6

Document Dom\NodeList class

bad5063

Document Dom\ParentNode interface

964689c

Document Dom\XMLDocument class

d33e068

Document Dom\TokenList class

8fa65e1

Document Dom\XPath class

f075814

Document Dom\Attr methods

a4e1efb

nielsdos force-pushed the dom-84 branch from 5011b8a to 0463c12 Compare December 3, 2024 20:17

nielsdos added 2 commits December 3, 2024 21:17

Document Dom\ChildNode methods

30d79eb

Document Dom\CharacterData methods

b757572

nielsdos force-pushed the dom-84 branch from 0463c12 to 1e6be82 Compare December 3, 2024 20:23

nielsdos added 2 commits December 3, 2024 21:23

Document Dom\Text methods

1e6be82

Document Dom\ParentNode methods

09f82dc

Girgias reviewed Dec 3, 2024

View reviewed changes

reference/dom/dom/characterdata/before.xml

Comment on lines +25 to +27

<para>

Adds nodes before the character data.

</para>

Copy link

Member

Girgias Dec 3, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simpara

Girgias reviewed Dec 3, 2024

View reviewed changes

reference/dom/dom/characterdata/remove.xml

Comment on lines +24 to +26

<para>

Removes the character data.

</para>

Copy link

Member

Girgias Dec 3, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

simpara

Girgias reviewed Dec 3, 2024

View reviewed changes

reference/dom/dom/attr/rename.xml

Comment on lines +46 to +49

<para>

&return.void;

</para>

</refsect1>

Copy link

Member

Girgias Dec 3, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

simpara

Girgias reviewed Dec 3, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] 8.4: Document all new DOM classes and methods #4212

[WIP] 8.4: Document all new DOM classes and methods #4212

nielsdos commented Dec 1, 2024 •

edited

Loading

nielsdos commented Dec 1, 2024 •

edited

Loading

Girgias left a comment

Girgias Dec 2, 2024

nielsdos Dec 2, 2024

nielsdos commented Dec 2, 2024

Girgias Dec 2, 2024

Girgias Dec 3, 2024

Girgias Dec 3, 2024

Girgias Dec 3, 2024

Girgias Dec 3, 2024

Girgias Dec 3, 2024

Girgias Dec 3, 2024

Girgias Dec 3, 2024

Girgias Dec 3, 2024

Girgias Dec 3, 2024

[WIP] 8.4: Document all new DOM classes and methods #4212

Are you sure you want to change the base?

[WIP] 8.4: Document all new DOM classes and methods #4212

Conversation

nielsdos commented Dec 1, 2024 • edited Loading

nielsdos commented Dec 1, 2024 • edited Loading

Girgias left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nielsdos commented Dec 2, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nielsdos commented Dec 1, 2024 •

edited

Loading

nielsdos commented Dec 1, 2024 •

edited

Loading