clarify fscanf/sscanf negative return value

Author: jordikroon

reference/filesystem/functions/fscanf.xml

@@ -64,6 +64,11 @@
    than there are available within <parameter>string</parameter>,
    &null; will be returned. On other errors, &false; will be returned.
   </simpara>
+  <simpara>
+   When optional parameters are used and the end of the input
+   <parameter>string</parameter> is reached before any value has been
+   parsed, <literal>-1</literal> is returned.
+  </simpara>
  </refsect1>
 
  <refsect1 role="examples">

reference/spl/splfileobject/fscanf.xml

@@ -40,11 +40,21 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <simpara>
-   If only one parameter is passed to this method, the values parsed will be
+   If only two parameters were passed to this function, the values parsed will be
    returned as an <type>array</type>. Otherwise, if optional parameters are passed,
    the function will return the number of assigned values. The optional
    parameters must be passed by reference.
   </simpara>
+  <simpara>
+   If there are more substrings expected in the <parameter>format</parameter>
+   than there are available within <parameter>string</parameter>,
+   &null; will be returned. On other errors, &false; will be returned.
+  </simpara>
+  <simpara>
+   When optional parameters are used and the end of the input
+   <parameter>string</parameter> is reached before any value has been
+   parsed, <literal>-1</literal> is returned.
+  </simpara>
  </refsect1>
 
  <refsect1 role="examples">

reference/strings/functions/sscanf.xml

@@ -63,6 +63,11 @@
    than there are available within <parameter>string</parameter>,
    &null; will be returned.
   </simpara>
+  <simpara>
+   When optional parameters are used and the end of the input
+   <parameter>string</parameter> is reached before any value has been
+   parsed, <literal>-1</literal> is returned.
+  </simpara>
  </refsect1>
 
  <refsect1 role="examples">