Some fixes to the 8.4 migration guide (#3910)

Author: Girgias

appendices/migration84/deprecated.xml

@@ -91,7 +91,7 @@ function foo(T1 $a, ?T2 $b, T3 $c) {}
 
    <simpara>
     This affects the exponentiation operator <literal>**</literal>
-    and the <function>pow</function>.
+    and the <function>pow</function> function.
    </simpara>
 
    <simpara>
@@ -337,7 +337,7 @@ class _MyClass {}
   <simpara>
    <function>lcg_value</function> is now deprecated,
    as the function is broken in multiple ways.
-   Use <methodname>\Random\Randomizer::getFloat</methodname> instead.
+   Use <methodname>Random\Randomizer::getFloat</methodname> instead.
   </simpara>
  </sect2>
 

appendices/migration84/incompatible.xml

@@ -459,10 +459,10 @@
 
   <simpara>
    Some DOM methods previously returned &false; or a
-   <constant>PHP_ERR</constant> <exceptionname>DOMException</exceptionname>
-   if a new node could not be allocated.
-   They now consistently throw an <constant>INVALID_STATE_ERR</constant>
-   <exceptionname>DOMException</exceptionname>.
+   <exceptionname>DOMException</exceptionname> with code
+   <constant>DOM_PHP_ERR</constant> if a new node could not be allocated.
+   They now consistently throw a <exceptionname>DOMException</exceptionname>
+   with code <constant>DOM_INVALID_STATE_ERR</constant>.
    This situation is extremely unlikely and the probability of being affected
    is low.
    As a result <methodname>DOMImplementation::createDocument</methodname>
@@ -626,8 +626,8 @@
   <title>PDO_DBLIB</title>
 
   <simpara>
-   The <constant>DBLIB_ATTR_STRINGIFY_UNIQUEIDENTIFIER</constant> and
-   <constant>DBLIB_ATTR_DATETIME_CONVERT</constant> attributes now act as
+   The <constant>Pdo\Dblib::ATTR_STRINGIFY_UNIQUEIDENTIFIER</constant> and
+   <constant>Pdo\Dblib::ATTR_DATETIME_CONVERT</constant> attributes now act as
    boolean attributes instead of integer attributes.
    Thus setting the attribute via <methodname>PDO::setAttribute</methodname>
    and retrieving it via <methodname>PDO::getAttribute</methodname> expects
@@ -639,7 +639,7 @@
   <title>PDO_FIREBIRD</title>
 
   <simpara>
-   The <constant>ATTR_AUTOCOMMIT</constant> attribute now act as
+   The <constant>PDO::ATTR_AUTOCOMMIT</constant> attribute now act as
    boolean attributes instead of integer attributes.
    Thus setting the attribute via <methodname>PDO::setAttribute</methodname>
    and retrieving it via <methodname>PDO::getAttribute</methodname> expects
@@ -657,9 +657,9 @@
   <title>PDO_MYSQL</title>
 
   <simpara>
-   The <constant>ATTR_AUTOCOMMIT</constant>,
-   <constant>ATTR_EMULATE_PREPARES</constant>, and
-   <constant>MYSQL_ATTR_DIRECT_QUERY</constant> attributes now act as
+   The <constant>PDO::ATTR_AUTOCOMMIT</constant>,
+   <constant>PDO::ATTR_EMULATE_PREPARES</constant>, and
+   <constant>PDO::MYSQL_ATTR_DIRECT_QUERY</constant> attributes now act as
    boolean attributes instead of integer attributes.
    Thus setting the attribute via <methodname>PDO::setAttribute</methodname>
    and retrieving it via <methodname>PDO::getAttribute</methodname> expects

appendices/migration84/other-changes.xml

@@ -371,7 +371,7 @@
 
    <simpara>
     The <parameter>backlog</parameter> parameter of
-    <function>socket_create_listen(</function> now has a default value of
+    <function>socket_create_listen</function> now has a default value of
     <constant>SOMAXCONN</constant>.
     Previously, it was <literal>128</literal>.
    </simpara>
@@ -446,39 +446,50 @@
     <title>Rounding with <function>round</function></title>
 
     <simpara>
-     The $mode parameter of the round() function has been widened to RoundingMode|int,
-     accepting instances of a new RoundingMode enum.
+     The <parameter>mode</parameter> parameter of the
+     <function>round</function> function has been widened to
+     <!-- TODO Proper union type -->
+     <literal>RoundingMode|int</literal>,
+     <!-- TODO should be <enumname> ? -->
+     accepting instances of a new <classname>RoundingMode</classname> enum.
      <!-- RFC: https://wiki.php.net/rfc/correctly_name_the_rounding_mode_and_make_it_an_enum -->
     </simpara>
 
-    <simpara>
-     Four new modes have been added to the round() function: RoundingMode::PositiveInfinity,
-     RoundingMode::NegativeInfinity, RoundingMode::TowardsZero, RoundingMode::AwayFromZero.
+    <para>
+     Four new modes have been added to the <function>round</function> function:
+     <simplelist type="inline">
+      <member><!-- <enumidentifier> -->RoundingMode::PositiveInfinity<!-- </enumidentifier> --></member>
+      <member><!-- <enumidentifier> -->RoundingMode::NegativeInfinity<!-- </enumidentifier> --></member>
+      <member><!-- <enumidentifier> -->RoundingMode::TowardsZero<!-- </enumidentifier> --></member>
+      <member><!-- <enumidentifier> -->RoundingMode::AwayFromZero<!-- </enumidentifier> --></member>
+     </simplelist>
      <!-- RFC: https://wiki.php.net/rfc/new_rounding_modes_to_round_function -->
-    </simpara>
+    </para>
 
     <simpara>
      The internal implementation for rounding to integers has been rewritten
      to be easier to verify for correctness and to be easier to maintain.
      Some rounding bugs have been fixed as a result of the rewrite.
-     For example previously rounding 0.49999999999999994 to the nearest integer
-     would have resulted in 1.0 instead of the correct result 0.0.
+     For example previously rounding <literal>0.49999999999999994</literal>
+     to the nearest integer would have resulted in <literal>1.0</literal>
+     instead of the correct result <literal>0.0</literal>.
      Additional inputs might also be affected and result in different outputs
      compared to earlier PHP versions.
     </simpara>
 
     <simpara>
-     Fixed a bug caused by "pre-rounding" of the round() function.
-     Previously, using "pre-rounding" to treat a value like 0.285
-     (actually 0.28499999999999998) as a decimal number and round it to 0.29.
+     Fixed a bug caused by "pre-rounding" of the <function>round</function> function.
+     Previously, using "pre-rounding" to treat a value like <literal>0.285</literal>
+     (actually <literal>0.28499999999999998</literal>) as a decimal number
+     and round it to <literal>0.29</literal>.
      However, "pre-rounding" incorrectly rounds certain numbers,
      so this fix removes "pre-rounding" and changes the way numbers are compared,
      so that the values are correctly rounded as decimal numbers.
     </simpara>
 
     <simpara>
-     The maximum precision that can be handled by round() has been extended
-     by one digit.
+     The maximum precision that can be handled by <function>round</function>
+     has been extended by one digit.
      For example, <code>round(4503599627370495.5)</code> returned in
      <literal>4503599627370495.5</literal>,
      but now returns <literal>4503599627370496</literal>.
@@ -617,9 +628,9 @@
    <simpara>
     Improved the performance of floating point number parsing and formatting in
     ZTS builds under highly concurrent loads.
-    This affects the <function>printf()</function> family of functions as well
+    This affects the <function>printf</function> family of functions as well
     as serialization functions such as <function>json_encode</function>,
-    or <function>serialize()</function>.
+    or <function>serialize</function>.
    </simpara>
 
    <simpara>
@@ -642,7 +653,7 @@
    <title>DOM</title>
 
    <simpara>
-    The performance of <methodname>DOMNode::C14N()</methodname> is greatly
+    The performance of <methodname>DOMNode::C14N</methodname> is greatly
     improved for the case without an xpath query.
     This can give a time improvement of easily two order of
     magnitude for documents with tens of thousands of nodes.
@@ -714,10 +725,10 @@
    <title>Random</title>
 
    <simpara>
-    Improved the performance of <classname>\Random\Randomizer</classname>,
+    Improved the performance of <classname>Random\Randomizer</classname>,
     with a specific focus on the
-    <methodname>\Random\Randomizer::getBytes</methodname>,
-    and <methodname>getBytesFromString()</methodname> methods.
+    <methodname>Random\Randomizer::getBytes</methodname>,
+    and <methodname>Random\Randomizer::getBytesFromString</methodname> methods.
    </simpara>
   </sect3>