ErrorToExceptionHandler: added documentation for trap() and trapAndRemoveFalse()

dktapps · dktapps · commit 41ff9c09f52f · 2022-01-07T23:16:40.000Z
diff --git a/src/ErrorToExceptionHandler.php b/src/ErrorToExceptionHandler.php
@@ -69,6 +69,10 @@ public static function set() : void{
 	}
 
 	/**
+	 * Runs the given closure inside the error-to-exception handler.
+	 * Using this function guarantees that any error will cause an exception to be thrown, regardless of whether the
+	 * global exception handler has been set properly or not.
+	 *
 	 * @phpstan-template TReturn
 	 * @phpstan-param \Closure() : TReturn $closure
 	 *
@@ -85,6 +89,9 @@ public static function trap(\Closure $closure){
 	}
 
 	/**
+	 * Same as trap(), but removes false from the set of possible return values. Mainly useful for PHPStan to unfalsify
+	 * the results of stdlib functions that normally return false when emitting warnings.
+	 *
 	 * @phpstan-template TReturn
 	 * @phpstan-param \Closure() : (TReturn|false) $closure
 	 *

Original file line number	Diff line number	Diff line change
`@@ -69,6 +69,10 @@ public static function set() : void{`
`69`	`69`	`}`
`70`	`70`
`71`	`71`	`/**`
	`72`	`+ * Runs the given closure inside the error-to-exception handler.`
	`73`	`+ * Using this function guarantees that any error will cause an exception to be thrown, regardless of whether the`
	`74`	`+ * global exception handler has been set properly or not.`
	`75`	`+ *`
`72`	`76`	`* @phpstan-template TReturn`
`73`	`77`	`* @phpstan-param \Closure() : TReturn $closure`
`74`	`78`	`*`
`@@ -85,6 +89,9 @@ public static function trap(\Closure $closure){`
`85`	`89`	`}`
`86`	`90`
`87`	`91`	`/**`
	`92`	`+ * Same as trap(), but removes false from the set of possible return values. Mainly useful for PHPStan to unfalsify`
	`93`	`+ * the results of stdlib functions that normally return false when emitting warnings.`
	`94`	`+ *`
`88`	`95`	`* @phpstan-template TReturn`
`89`	`96`	`* @phpstan-param \Closure() : (TReturn\|false) $closure`
`90`	`97`	`*`