more docs

Author: shish

CONTRIBUTING.md

@@ -35,6 +35,27 @@ Safe-PHP code is generated automatically from the PHP doc.
   `generated/` and the files in `lib/` auto-loaded; they shouldn't
   need to worry about any files outside those two directories.
 
+### Compatibility with upstream PHP
+
+Intentional changes:
+* Functions which return a special value to indicate an error should now throw an `Exception`.
+  * eg `file_get_contents()` returns a `string` on success, or returns `false` on error.
+    `\Safe\file_get_contents()` returns a `string` on success and throws an `Exception` on error.
+* If the return type included that type only for errors, that type is removed from the signature.
+  * eg `file_get_contents()` returns `string|false`, `\Safe\file_get_contents()` returns `string`
+  * `proc_close()` returns the process exit code on success and -1 on error.
+    Both of these are `int`, so the signature remains `int`.
+* If the function returned `true` on success and `false` on error, and we have
+  removed the `false`, then the signature gets changed from `bool` to `void` to
+  stop people from accidentally writing `if(function()) {...}`
+
+Necessary changes / side effects:
+* Functions which have optional parameters without defaults (eg `cubrid_bind()` has
+  `$bind_value_type`) are turned into functions with nullable parameters which
+  default to `null`.
+* PHP's internal error marker (The thing retrieved by `error_get_last()`) will be cleared
+  each time a Safe function is called.
+
 ## Minimum Supported PHP Version
 
 See https://www.php.net/supported-versions.php
@@ -97,7 +118,7 @@ $ php ./safe.php generate
 
 ### Detecting new cases
 
-`generator/src/XmlDocParser/DocPage.php` uses a list of regexes to scan the
+`generator/config/detectErrorType.php` uses a list of regexes to scan the
 documentation looking for functions which return `false` (or `null`) on error.
 If you want to add support for more functions to Safe-PHP, the easiest way is
 to add more regexes here.
@@ -106,6 +127,14 @@ If you detect more cases where `false` is an exception, then you should
 probably also edit `Method.php::stripReturnFalseText()` to remove the
 "returns false on error" text from the documentation.
 
+### Deprecating old cases
+
+If the unsafe-function-detector has made a false-positive (ie, it has detected
+a function returns `false` on error, when actually `false` is fine), then we
+don't want to completely remove the function because that would break backwards
+compatibility, but we can hide the function to avoid it being suggested to
+new users.
+
 ### Special cases
 
 In some cases, automatic generation is too difficult to execute and the function has to be written manually.