Cleanup docs related to @ operator

Also fix part of the set_error_handler() docs

language/error-handling.xml

@@ -261,6 +261,13 @@ A custom function for this type of exception
    <literal linkend="language.operators.errorcontrol">@</literal> operator.
   </para>
 
+  <warning>
+   <para>
+    Prior to PHP 8.0.0 it was possible to suppress critical diagnostics that
+    would terminate the execution of the PHP script.
+   </para>
+  </warning>
+
   <note>
    <para>
     Diagnostics can be added, removed, have their severity altered or be

language/operators.xml

@@ -1848,16 +1848,41 @@ echo $foo ?? $bar ?? $baz ?? $qux; // outputs 1
   <sect1 xml:id="language.operators.errorcontrol">
    <title>Error Control Operators</title>
    <simpara>
-    PHP supports one error control operator: the at sign (@). When
-    prepended to an expression in PHP, any error messages that might
-    be generated by that expression will be ignored.
-   </simpara>
-   <simpara>
-    If you have set a custom error handler function with
-    <function>set_error_handler</function> then it will still get
-    called, but this custom error handler can (and should) call <function>error_reporting</function>
-    which will return 0 when the call that triggered the error was preceded by an @.
+    PHP supports one error control operator: the at sign (<literal>@</literal>).
+    When prepended to an expression in PHP, any diagnostic error that might
+    be generated by that expression will be suppressed.
    </simpara>
+   <para>
+    If a custom error handler function is set with
+    <function>set_error_handler</function>, it will still be called even though
+    the diagnostic has been suppressed, as such the custom error handler should
+    call <function>error_reporting</function> and verify that the
+    <literal>@</literal> operator was used in the following way:
+
+    <informalexample>
+     <programlisting role="php">
+<![CDATA[
+<?php
+function my_error_handler($err_no, $err_msg, $filename, $linenum) {
+    if (!(error_reporting() & $err_no)) {
+        return false; // Silenced
+    }
+    // ...
+}
+?>
+]]>
+     </programlisting>
+    </informalexample>
+   </para>
+
+   <warning>
+    <para>
+     Prior to PHP 8.0.0, the value of the severity passed to the custom error
+     handler was always <literal>0</literal> if the diagnostic was suppressed.
+     This is no longer the case as of PHP 8.0.0.
+    </para>
+   </warning>
+
    <simpara>
     Any error message generated by the expression is available in the <literal>"message"</literal>
     element of the array returned by <function>error_get_last</function>.
@@ -1883,23 +1908,23 @@ $value = @$cache[$key];
    </para>
    <note>
     <simpara>
-     The @-operator works only on
-     <link linkend="language.expressions">expressions</link>. A simple rule
-     of thumb is: if you can take the value of something, you can prepend
-     the @ operator to it. For instance, you can prepend it to variables,
-     function and <function>include</function> calls, constants, and
-     so forth. You cannot prepend it to function or class definitions,
+     The <literal>@</literal>-operator works only on
+     <link linkend="language.expressions">expressions</link>.
+     A simple rule of thumb is: if one can take the value of something,
+     then one can prepend the <literal>@</literal> operator to it.
+     For instance, it can be prepended to variables, functions,
+     <function>include</function> calls, constants, and so forth.
+     It cannot be prepended to function or class definitions,
      or conditional structures such as <literal>if</literal> and
      &foreach;, and so forth.
     </simpara>
    </note>
    <warning>
     <para>
-     Currently the "@" error-control operator prefix will even disable
-     error reporting for critical errors that will terminate script
-     execution. Among other things, this means that if you use "@" to
-     suppress errors from a certain function and either it isn't
-     available or has been mistyped, the script will die right there
+     Prior to PHP 8.0.0, it was possible for the <literal>@</literal> operator
+     to disable critical errors that will terminate script execution.
+     For example, suppressing a function which did not exist, by being
+     unavailable or mistyped, would cause the script to die
      with no indication as to why.
     </para>
    </warning>

reference/errorfunc/functions/set-error-handler.xml

@@ -32,11 +32,18 @@
    error handler will be called regardless - however you are still able to read 
    the current value of 
    <link linkend="ini.error-reporting">error_reporting</link> and act
-   appropriately. Of particular note is that this value will be 0 if the
-   statement that caused the error was prepended by the
-   <link linkend="language.operators.errorcontrol">@ error-control
-   operator</link>.
+   appropriately.
   </para>
+
+  <warning>
+   <para>
+    Prior to PHP 8.0.0, the <parameter>errno</parameter> value was always
+    <literal>0</literal> if the expression which caused the diagnostic
+    was prepended by the
+    <link linkend="language.operators.errorcontrol">@ error-control operator</link>.
+   </para>
+  </warning>
+
   <para>
    Also note that it is your responsibility to <function>die</function> if
    necessary. If the error-handler function returns, script execution
@@ -186,6 +193,14 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>8.0.0</entry>
+       <entry>
+        <parameter>errno</parameter> is no longer <literal>0</literal> when
+        the expression was suppressed by the
+        <link linkend="language.operators.errorcontrol">@ error-control operator</link>
+       </entry>
+      </row>
       <row>
        <entry>8.0.0</entry>
        <entry>