Improve phpDoc class docs

Author: PhrozenByte

psalm.xml

@@ -1,4 +1,20 @@
 <?xml version="1.0"?>
+<!--
+  ~ PHPUnitThrowableAssertions - Throwable-related PHPUnit assertions.
+  ~
+  ~ @copyright Copyright (c) 2021, Daniel Rudolf (<https://www.daniel-rudolf.de>)
+  ~
+  ~ This file is copyrighted by the contributors recorded in the version control
+  ~ history of the file, available from the following original location:
+  ~
+  ~ <https://github.com/PhrozenByte/phpunit-throwable-asserts/blob/master/psalm.xml>
+  ~
+  ~ @license http://opensource.org/licenses/MIT The MIT License
+  ~
+  ~ SPDX-License-Identifier: MIT
+  ~ License-Filename: LICENSE
+  -->
+
 <psalm
     errorLevel="4"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

src/Assert.php

@@ -22,9 +22,8 @@
 /**
  * A set of throwable-related assertion methods.
  *
- * This static class just uses the `ThrowableAssertsTrait` trait. Refer to
- * {@class PhrozenByte\PHPUnitThrowableAsserts\ThrowableAssertsTrait} for
- * more info.
+ * This static class just uses the {@see ThrowableAssertsTrait} trait. Refer to
+ * {@see ThrowableAssertsTrait} for more info.
  */
 class Assert
 {

src/Constraint/AbstractCallableThrows.php

@@ -21,7 +21,6 @@
 
 use PHPUnit\Framework\Constraint\Constraint;
 use PHPUnit\Framework\Constraint\IsEqual;
-use PHPUnit\Framework\Exception as PHPUnitException;
 use PHPUnit\Framework\ExpectationFailedException;
 use PHPUnit\Framework\InvalidArgumentException;
 use PhrozenByte\PHPUnitThrowableAsserts\CallableProxy;
@@ -31,6 +30,8 @@
 /**
  * Abstract base class for the `CallableThrows` and `CallableThrowsNot`
  * constraints implementing some common methods.
+ *
+ * @internal
  */
 abstract class AbstractCallableThrows extends Constraint
 {
@@ -54,7 +55,7 @@ abstract class AbstractCallableThrows extends Constraint
      * @param int|string|null        $code       value to match the Throwable's code
      * @param bool                   $exactMatch whether an exact match of the Throwable's class is required
      *
-     * @throws PHPUnitException
+     * @throws InvalidArgumentException
      */
     public function __construct(string $className, $message, $code, bool $exactMatch)
     {
@@ -74,7 +75,16 @@ public function __construct(string $className, $message, $code, bool $exactMatch
     }
 
     /**
-     * {@inheritDoc}
+     * Throws a ExpectationFailedException exception for the compared value.
+     *
+     * @param mixed                  $other             evaluated value or object
+     * @param string                 $description       additional information about the test
+     * @param ComparisonFailure|null $comparisonFailure additional information about string inequality
+     * @param Throwable|null         $throwable         instance of a unexpectedly thrown Throwable
+     *
+     * @throws ExpectationFailedException
+     *
+     * @psalm-return never-return
      */
     protected function fail(
         $other,
@@ -105,7 +115,7 @@ protected function fail(
     }
 
     /**
-     * Returns additional failure description for a Throwable
+     * Returns additional failure description for a Throwable.
      *
      * @param Throwable|null $throwable the Throwable that was thrown
      *
@@ -133,7 +143,14 @@ protected function throwableFailureDescription(?Throwable $throwable): string
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the description of the failure.
+     *
+     * The beginning of failure messages is "Failed asserting that" in most
+     * cases. This method should return the second part of that sentence.
+     *
+     * @param mixed $other the evaluated value
+     *
+     * @return string the failure description
      */
     protected function failureDescription($other): string
     {
@@ -149,7 +166,7 @@ protected function failureDescription($other): string
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the number of assertions performed by this Constraint.
      */
     public function count(): int
     {

src/Constraint/CallableThrows.php

@@ -20,6 +20,7 @@
 namespace PhrozenByte\PHPUnitThrowableAsserts\Constraint;
 
 use PHPUnit\Framework\Constraint\Constraint;
+use PHPUnit\Framework\Exception as PHPUnitException;
 use PHPUnit\Framework\ExpectationFailedException;
 use PHPUnit\Framework\InvalidArgumentException;
 use Throwable;
@@ -75,7 +76,9 @@ public function __construct(
     }
 
     /**
-     * @inheritDoc
+     * Returns a human-readable string representation of this Constraint.
+     *
+     * @return string string representation of the Constraint
      */
     public function toString(): string
     {
@@ -87,7 +90,23 @@ public function toString(): string
     }
 
     /**
-     * {@inheritDoc}
+     * Evaluates whether the given value matches the Constraint.
+     *
+     * If `$returnResult` is set to `false` (default), an exception is thrown
+     * in case of a failure. `null` is returned otherwise.
+     *
+     * If `$returnResult` is `true`, the result of the evaluation is returned
+     * as a boolean instead: `true` in case of success, `false` in case of a
+     * failure.
+     *
+     * @param mixed  $other        the value to evaluate
+     * @param string $description  additional information about the test
+     * @param bool   $returnResult whether to return the evaluation result
+     *
+     * @return bool|null evaluation result if `$returnResult` is set `true`
+     *
+     * @throws ExpectationFailedException
+     * @throws PHPUnitException
      */
     public function evaluate($other, string $description = '', bool $returnResult = false)
     {

src/Constraint/CallableThrowsNot.php

@@ -22,6 +22,7 @@
 use PHPUnit\Framework\Constraint\Constraint;
 use PHPUnit\Framework\Exception as PHPUnitException;
 use PHPUnit\Framework\ExpectationFailedException;
+use PHPUnit\Framework\InvalidArgumentException;
 use Throwable;
 
 /**
@@ -52,7 +53,7 @@ class CallableThrowsNot extends AbstractCallableThrows
      * @param int|string|null        $code       catch Throwables with the given code only
      * @param bool                   $exactMatch whether an exact match of the Throwable class is caught only
      *
-     * @throws PHPUnitException
+     * @throws InvalidArgumentException
      */
     public function __construct(
         string $className = Throwable::class,
@@ -64,7 +65,9 @@ public function __construct(
     }
 
     /**
-     * @inheritDoc
+     * Returns a human-readable string representation of this Constraint.
+     *
+     * @return string string representation of the Constraint
      */
     public function toString(): string
     {
@@ -76,7 +79,23 @@ public function toString(): string
     }
 
     /**
-     * {@inheritDoc}
+     * Evaluates whether the given value matches the Constraint.
+     *
+     * If `$returnResult` is set to `false` (default), an exception is thrown
+     * in case of a failure. `null` is returned otherwise.
+     *
+     * If `$returnResult` is `true`, the result of the evaluation is returned
+     * as a boolean instead: `true` in case of success, `false` in case of a
+     * failure.
+     *
+     * @param mixed  $other        the value to evaluate
+     * @param string $description  additional information about the test
+     * @param bool   $returnResult whether to return the evaluation result
+     *
+     * @return bool|null evaluation result if `$returnResult` is set `true`
+     *
+     * @throws ExpectationFailedException
+     * @throws PHPUnitException
      */
     public function evaluate($other, string $description = '', bool $returnResult = false)
     {

src/ThrowableAssertsTrait.php

@@ -28,6 +28,23 @@
 use PhrozenByte\PHPUnitThrowableAsserts\Constraint\CallableThrowsNot;
 use Throwable;
 
+/**
+ * A set of Throwable-related assertion methods.
+ *
+ * This trait implements an assertion method and constraint creation method per
+ * implemented constraint, namely
+ *
+ * - the `assertCallableThrows()` and `callableThrows()` methods for
+ *   {@see CallableThrows}, and
+ * - the `assertCallableThrowsNot()` and `callableThrowsNot()` methods for
+ *   {@see CallableThrowsNot}.
+ *
+ * This trait additionally implements some helper methods to create new
+ * instances of the callable proxy classes, namely
+ *
+ * - the `callableProxy()` method for {@see CallableProxy}, and
+ * - the `cachedCallableProxy()` method for {@see CachedCallableProxy}.
+ */
 trait ThrowableAssertsTrait
 {
     /**
@@ -156,7 +173,7 @@ public static function callableThrowsNot(
 
     /**
      * Returns a new instance of CallableProxy.
-     * *
+     *
      * @param callable $callable     the Callable to invoke
      * @param mixed    ...$arguments the arguments to pass to the Callable
      *
@@ -169,7 +186,7 @@ public static function callableProxy(callable $callable, ...$arguments): Callabl
 
     /**
      * Returns a new instance of CachedCallableProxy.
-     * *
+     *
      * @param callable $callable     the Callable to invoke
      * @param mixed    ...$arguments the arguments to pass to the Callable
      *

tests/Utils/TestConstraint.php

@@ -48,23 +48,23 @@ public function __construct(array $options = [])
     }
 
     /**
-     * @inheritDoc
+     * {@inheritDoc}
      */
     public function toString(): string
     {
         return $this->toString;
     }
 
     /**
-     * @inheritDoc
+     * {@inheritDoc}
      */
     protected function matches($other): bool
     {
         return $this->matches;
     }
 
     /**
-     * @inheritDoc
+     * {@inheritDoc}
      */
     public function count(): int
     {