Improve callmap docs

Author: danog

composer.json

@@ -75,7 +75,8 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "6.x-dev",
+            "dev-master": "7.x-dev",
+            "dev-6.x": "6.x-dev",
             "dev-5.x": "5.x-dev",
             "dev-4.x": "4.x-dev",
             "dev-3.x": "3.x-dev",

docs/contributing/editing_callmaps.md

@@ -33,6 +33,54 @@ optional parameter is postfixed with `=`, references with `&`/`&r_`/`&w_`/`&rw_`
 (depending on the read/write meaning of the reference param) and 
 variadic args are prefixed with `...`.
 
+Callmaps also support function aliases: aliases are very useful to specify that
+a certain function behaves differently according to the parameter types.
+
+For example, the following aliases are currently in use in the callmap to specify 
+that the `version_compare` function can be called with an `operator` parameter, 
+in which case it will return a boolean; otherwise it will return an integer.  
+
+```php
+[
+    'version_compare' => [
+        0 => 'bool',
+        'version1' => 'string',
+        'version2' => 'string',
+        'operator' => '\'!=\'|\'<\'|\'<=\'|\'<>\'|\'=\'|\'==\'|\'>\'|\'>=\'|\'eq\'|\'ge\'|\'gt\'|\'le\'|\'lt\'|\'ne\'|null',
+    ],
+    'version_compare\'1' => [
+        0 => 'int',
+        'version1' => 'string',
+        'version2' => 'string',
+    ],
+]
+```
+
+**Note**: the above example doesn't provide almost any useful information for type inference;
+in fact, the real logic for return type inference is contained in the `VersionCompareReturnTypeProvider`.  
+
+The callmap is mainly useful when treating functions and methods as *callable values*, for example:
+
+```php
+<?php
+function naive_version_compare(string $a, string $b, ?string $operator = null): int|bool {
+    return 0;
+}
+
+$a = ["1.0", "2.0"];
+
+// OK
+usort($a, "version_compare");
+
+// InvalidArgument: Argument 2 of usort expects callable(string, string):int, but impure-callable(string, string, null|string=):(bool|int) provided
+usort($a, "naive_version_compare");
+```
+
+The first usort succeeds, because psalm chooses the correct alias to use between the two provided in the callmap.  
+The second usort fails (equivalent to the non-split return type of `version_compare` inferred by reflection), because the return type is a union of the two possible signatures of version_compare.  
+
+When you have multifaceted functions like these, it's a very good idea to at least define a templated stub in `stubs/` for them, or a custom return type provider for even more complex logic, not representable with templates/conditional types/etc in a stub.
+
 ## Delta file format
 
 Delta files (named `CallMap_<PHP major version><PHP minor version>_delta.php`)