improved phpDoc

Author: dg

src/Framework/DataProvider.php

@@ -11,13 +11,13 @@
 
 
 /**
- * Data provider helpers.
+ * Utility class for providing data from various sources for tests.
  * @internal
  */
 class DataProvider
 {
 	/**
-	 * @throws \Exception
+	 * Loads data from a specified file and filters them based on a query string. Supports both PHP files and INI files.
 	 */
 	public static function load(string $file, string $query = ''): array
 	{
@@ -34,7 +34,7 @@ public static function load(string $file, string $query = ''): array
 				throw new \Exception("Data provider '$file' did not return array or Traversable.");
 			}
 		} else {
-			$data = @parse_ini_file($file, process_sections: true); // @ is escalated to exception
+			$data = @parse_ini_file($file, process_sections: true);
 			if ($data === false) {
 				throw new \Exception("Cannot parse data provider file '$file'.");
 			}
@@ -50,6 +50,9 @@ public static function load(string $file, string $query = ''): array
 	}
 
 
+	/**
+	 * Evaluates a query against a set of data keys to determine if the key matches the criteria.
+	 */
 	public static function testQuery(string $input, string $query): bool
 	{
 		$replaces = ['' => '=', '=>' => '>=', '=<' => '<='];
@@ -70,6 +73,9 @@ public static function testQuery(string $input, string $query): bool
 	}
 
 
+	/**
+	 * Compares two values using the specified operator.
+	 */
 	private static function compare(mixed $l, string $operator, mixed $r): bool
 	{
 		return match ($operator) {
@@ -85,7 +91,7 @@ private static function compare(mixed $l, string $operator, mixed $r): bool
 
 
 	/**
-	 * @throws \Exception
+	 * Parses a data provider annotation from a test method to extract the file path and query.
 	 */
 	public static function parseAnnotation(string $annotation, string $file): array
 	{

src/Framework/DomQuery.php

@@ -15,6 +15,9 @@
  */
 class DomQuery extends \SimpleXMLElement
 {
+	/**
+	 * Creates a DomQuery object from an HTML string.
+	 */
 	public static function fromHtml(string $html): self
 	{
 		if (!str_contains($html, '<')) {
@@ -48,14 +51,17 @@ public static function fromHtml(string $html): self
 	}
 
 
+	/**
+	 * Creates a DomQuery object from an XML string.
+	 */
 	public static function fromXml(string $xml): self
 	{
 		return simplexml_load_string($xml, self::class);
 	}
 
 
 	/**
-	 * Returns array of descendants filtered by a selector.
+	 * Finds descendants of current element that match the given CSS selector.
 	 * @return DomQuery[]
 	 */
 	public function find(string $selector): array
@@ -65,7 +71,7 @@ public function find(string $selector): array
 
 
 	/**
-	 * Check the current document against a selector.
+	 * Checks if any descendant of current element matches the given selector.
 	 */
 	public function has(string $selector): bool
 	{
@@ -74,7 +80,7 @@ public function has(string $selector): bool
 
 
 	/**
-	 * Transforms CSS expression to XPath.
+	 * Converts a CSS selector into an XPath expression.
 	 */
 	public static function css2xpath(string $css): string
 	{

src/Framework/TestCase.php

@@ -27,7 +27,7 @@ class TestCase
 
 
 	/**
-	 * Runs the test case.
+	 * Runs all test methods in this test case or a specific test method if provided.
 	 */
 	public function run(): void
 	{
@@ -69,8 +69,8 @@ public function run(): void
 
 
 	/**
-	 * Runs the test method.
-	 * @param  array  $args  test method parameters (dataprovider bypass)
+	 * Executes a specified test method within this test case, handling data providers and errors.
+	 * @param  ?array  $args  arguments provided for the test method, bypassing data provider if provided.
 	 */
 	public function runTest(string $method, ?array $args = null): void
 	{
@@ -165,7 +165,7 @@ protected function getData(string $provider)
 
 
 	/**
-	 * This method is called before a test is executed.
+	 * Setup logic to be executed before each test method. Override in subclasses for specific behaviors.
 	 * @return void
 	 */
 	protected function setUp()
@@ -174,14 +174,17 @@ protected function setUp()
 
 
 	/**
-	 * This method is called after a test is executed.
+	 * Teardown logic to be executed after each test method. Override in subclasses to release resources.
 	 * @return void
 	 */
 	protected function tearDown()
 	{
 	}
 
 
+	/**
+	 * Executes the tearDown method and suppresses any errors, ensuring clean teardown in all cases.
+	 */
 	private function silentTearDown(): void
 	{
 		set_error_handler(fn() => null);
@@ -195,14 +198,17 @@ private function silentTearDown(): void
 
 
 	/**
-	 * Skips the test.
+	 * Skips the current test, optionally providing a reason for skipping.
 	 */
 	protected function skip(string $message = ''): void
 	{
 		throw new TestCaseSkippedException($message);
 	}
 
 
+	/**
+	 * Outputs a list of all test methods in the current test case. Used for Runner.
+	 */
 	private function sendMethodList(array $methods): void
 	{
 		Environment::$checkAssertions = false;
@@ -230,6 +236,9 @@ private function sendMethodList(array $methods): void
 	}
 
 
+	/**
+	 * Prepares test data from specified data providers or default method parameters if no provider is specified.
+	 */
 	private function prepareTestData(\ReflectionMethod $method, array $dataprovider): array
 	{
 		$data = $defaultParams = [];
@@ -270,12 +279,16 @@ private function prepareTestData(\ReflectionMethod $method, array $dataprovider)
 	}
 }
 
-
+/**
+ * Errors specific to TestCase operations.
+ */
 class TestCaseException extends \Exception
 {
 }
 
-
+/**
+ * Exception thrown when a test case or a test method is skipped.
+ */
 class TestCaseSkippedException extends \Exception
 {
 }

src/Framework/functions.php

@@ -7,10 +7,13 @@
 use Tester\Environment;
 
 
+/**
+ * Executes a provided test closure, handling setup and teardown operations.
+ */
 function test(string $description, Closure $closure): void
 {
 	if (($count = func_num_args()) > 2) {
-		throw new \Exception(__FUNCTION__ . "() expects 2 parameter, $count given.");
+		throw new Exception(__FUNCTION__ . "() expects 2 parameters, $count given.");
 	}
 
 	if ($fn = (new ReflectionFunction('setUp'))->getStaticVariables()['fn']) {
@@ -36,6 +39,9 @@ function test(string $description, Closure $closure): void
 }
 
 
+/**
+ * Tests for exceptions thrown by a provided closure matching specific criteria.
+ */
 function testException(
 	string $description,
 	Closure $function,
@@ -59,13 +65,19 @@ function testException(
 }
 
 
+/**
+ * Registers a function to be called before each test execution.
+ */
 function setUp(?Closure $closure): void
 {
 	static $fn;
 	$fn = $closure;
 }
 
 
+/**
+ * Registers a function to be called after each test execution.
+ */
 function tearDown(?Closure $closure): void
 {
 	static $fn;