From 7fe7146dc3dbfb11754b98ecf53d93062829cade Mon Sep 17 00:00:00 2001
From: feek <5747667+mr-feek@users.noreply.github.com>
Date: Tue, 11 Aug 2020 04:29:45 -0700
Subject: [PATCH] docs: provide some background as to what certain hooks are
 for (#3978)

---
 src/Psalm/Plugin/Hook/FunctionExistenceProviderInterface.php  | 4 ++++
 src/Psalm/Plugin/Hook/FunctionReturnTypeProviderInterface.php | 4 ++++
 src/Psalm/Plugin/Hook/MethodExistenceProviderInterface.php    | 4 ++++
 src/Psalm/Plugin/Hook/MethodReturnTypeProviderInterface.php   | 4 ++++
 src/Psalm/Plugin/Hook/PropertyExistenceProviderInterface.php  | 4 ++++
 5 files changed, 20 insertions(+)

diff --git a/src/Psalm/Plugin/Hook/FunctionExistenceProviderInterface.php b/src/Psalm/Plugin/Hook/FunctionExistenceProviderInterface.php
index 1344ec30b..78f87ef17 100644
--- a/src/Psalm/Plugin/Hook/FunctionExistenceProviderInterface.php
+++ b/src/Psalm/Plugin/Hook/FunctionExistenceProviderInterface.php
@@ -11,6 +11,10 @@ interface FunctionExistenceProviderInterface
     public static function getFunctionIds() : array;
 
     /**
+     * Use this hook for informing whether or not a global function exists. If you know the function does
+     * not exist, return false. If you aren't sure if it exists or not, return null and the default analysis will continue
+     * to determine if the function actually exists.
+     *
      * @return ?bool
      */
     public static function doesFunctionExist(
diff --git a/src/Psalm/Plugin/Hook/FunctionReturnTypeProviderInterface.php b/src/Psalm/Plugin/Hook/FunctionReturnTypeProviderInterface.php
index 97fede166..8954f86d8 100644
--- a/src/Psalm/Plugin/Hook/FunctionReturnTypeProviderInterface.php
+++ b/src/Psalm/Plugin/Hook/FunctionReturnTypeProviderInterface.php
@@ -15,6 +15,10 @@ interface FunctionReturnTypeProviderInterface
     public static function getFunctionIds() : array;
 
     /**
+     * Use this hook for providing custom return type logic. If this plugin does not know what a function should return
+     * but another plugin may be able to determine the type, return null. Otherwise return a mixed union type if something
+     * should be returned, but can't be more specific.
+     *
      * @param  array<PhpParser\Node\Arg>    $call_args
      *
      * @return ?Type\Union
diff --git a/src/Psalm/Plugin/Hook/MethodExistenceProviderInterface.php b/src/Psalm/Plugin/Hook/MethodExistenceProviderInterface.php
index d4d826936..33fff18be 100644
--- a/src/Psalm/Plugin/Hook/MethodExistenceProviderInterface.php
+++ b/src/Psalm/Plugin/Hook/MethodExistenceProviderInterface.php
@@ -12,6 +12,10 @@ interface MethodExistenceProviderInterface
     public static function getClassLikeNames() : array;
 
     /**
+     * Use this hook for informing whether or not a method exists on a given object. If you know the method does
+     * not exist, return false. If you aren't sure if it exists or not, return null and the default analysis will continue
+     * to determine if the method actually exists.
+     *
      * @return ?bool
      */
     public static function doesMethodExist(
diff --git a/src/Psalm/Plugin/Hook/MethodReturnTypeProviderInterface.php b/src/Psalm/Plugin/Hook/MethodReturnTypeProviderInterface.php
index 9c347b1db..b497bc05f 100644
--- a/src/Psalm/Plugin/Hook/MethodReturnTypeProviderInterface.php
+++ b/src/Psalm/Plugin/Hook/MethodReturnTypeProviderInterface.php
@@ -15,6 +15,10 @@ interface MethodReturnTypeProviderInterface
     public static function getClassLikeNames() : array;
 
     /**
+     * Use this hook for providing custom return type logic. If this plugin does not know what a method should return
+     * but another plugin may be able to determine the type, return null. Otherwise return a mixed union type if something
+     * should be returned, but can't be more specific.
+     *
      * @param  array<PhpParser\Node\Arg>    $call_args
      * @param  ?array<Type\Union> $template_type_parameters
      * @param lowercase-string $method_name_lowercase
diff --git a/src/Psalm/Plugin/Hook/PropertyExistenceProviderInterface.php b/src/Psalm/Plugin/Hook/PropertyExistenceProviderInterface.php
index edea5aa10..bcd0e1d56 100644
--- a/src/Psalm/Plugin/Hook/PropertyExistenceProviderInterface.php
+++ b/src/Psalm/Plugin/Hook/PropertyExistenceProviderInterface.php
@@ -13,6 +13,10 @@ interface PropertyExistenceProviderInterface
     public static function getClassLikeNames() : array;
 
     /**
+     * Use this hook for informing whether or not a property exists on a given object. If you know the property does
+     * not exist, return false. If you aren't sure if it exists or not, return null and the default analysis will continue
+     * to determine if the property actually exists.
+     *
      * @return ?bool
      */
     public static function doesPropertyExist(