improved PHPDoc descriptions

Author: dg

src/Routing/Route.php

@@ -13,8 +13,7 @@
 
 
 /**
- * The bidirectional route is responsible for mapping
- * HTTP request to an array for dispatch and vice-versa.
+ * Bidirectional route mapping between HTTP requests and parameter arrays using a URL mask.
  */
 class Route implements Router
 {
@@ -107,9 +106,6 @@ public function __construct(string $mask, array $metadata = [])
 	}
 
 
-	/**
-	 * Returns mask.
-	 */
 	public function getMask(): string
 	{
 		return $this->mask;
@@ -126,10 +122,7 @@ protected function getMetadata(): array
 	}
 
 
-	/**
-	 * Returns default values.
-	 * @return array<string, mixed>
-	 */
+	/** @return array<string, mixed> */
 	public function getDefaults(): array
 	{
 		$defaults = [];
@@ -144,6 +137,7 @@ public function getDefaults(): array
 
 
 	/**
+	 * Returns parameters that must have a specific fixed value for the route to match.
 	 * @internal
 	 * @return array<string, mixed>
 	 */
@@ -160,10 +154,7 @@ public function getConstantParameters(): array
 	}
 
 
-	/**
-	 * Maps HTTP request to an array.
-	 * @return ?array<string, mixed>
-	 */
+	/** @return ?array<string, mixed> */
 	public function match(Nette\Http\IRequest $httpRequest): ?array
 	{
 		// combine with precedence: mask (params in URL-path), fixity, query, (post,) defaults
@@ -258,10 +249,7 @@ public function match(Nette\Http\IRequest $httpRequest): ?array
 	}
 
 
-	/**
-	 * Constructs absolute URL from array.
-	 * @param array<string, mixed>  $params
-	 */
+	/** @param array<string, mixed>  $params */
 	public function constructUrl(array $params, Nette\Http\UrlScript $refUrl): ?string
 	{
 		if (!$this->preprocessParams($params)) {
@@ -620,7 +608,7 @@ private function parseQuery(array $parts): bool
 
 
 	/**
-	 * Rename keys in array.
+	 * Renames keys in array according to the translation table.
 	 * @param array<string, mixed>  $arr
 	 * @param array<string, string>  $xlat
 	 * @return array<string, mixed>
@@ -647,7 +635,7 @@ private static function renameKeys(array $arr, array $xlat): array
 
 
 	/**
-	 * Url encode.
+	 * Encodes a parameter value for use in a URL path segment, leaving allowed characters unencoded.
 	 */
 	public static function param2path(string $s): string
 	{

src/Routing/RouteList.php

@@ -12,7 +12,7 @@
 
 
 /**
- * The router broker.
+ * Router collection that tries each router in sequence and caches URL construction lookups.
  */
 class RouteList implements Router
 {
@@ -38,7 +38,6 @@ public function __construct()
 
 
 	/**
-	 * Maps HTTP request to an array.
 	 * @return ?array<string, mixed>
 	 * @final
 	 */
@@ -95,10 +94,7 @@ protected function completeParameters(array $params): ?array
 	}
 
 
-	/**
-	 * Constructs absolute URL from array.
-	 * @param array<string, mixed>  $params
-	 */
+	/** @param array<string, mixed>  $params */
 	public function constructUrl(array $params, Nette\Http\UrlScript $refUrl): ?string
 	{
 		if ($this->domain) {
@@ -141,6 +137,10 @@ public function constructUrl(array $params, Nette\Http\UrlScript $refUrl): ?stri
 	}
 
 
+	/**
+	 * Builds an internal lookup index of routers grouped by their most discriminating constant parameter.
+	 * Call this before URL generation to improve performance; called automatically on first use.
+	 */
 	public function warmupCache(): void
 	{
 		// find best key
@@ -232,6 +232,7 @@ protected function modify(int $index, ?Router $router): void
 
 
 	/**
+	 * Creates a Route from the mask and adds it to the list.
 	 * @param string  $mask e.g. '<presenter>/<action>/<id \d{1,3}>'
 	 * @param array<string, mixed>  $metadata default values or metadata
 	 * @return static
@@ -244,7 +245,7 @@ public function addRoute(string $mask, array $metadata = [], int $oneWay = 0)
 
 
 	/**
-	 * Returns an iterator over all routers.
+	 * Creates a child RouteList scoped to the given domain and adds it to this list.
 	 */
 	public function withDomain(string $domain): static
 	{
@@ -257,6 +258,9 @@ public function withDomain(string $domain): static
 	}
 
 
+	/**
+	 * Creates a child RouteList scoped to the given path prefix and adds it to this list.
+	 */
 	public function withPath(string $path): static
 	{
 		$router = new static;
@@ -268,13 +272,17 @@ public function withPath(string $path): static
 	}
 
 
+	/**
+	 * Returns the parent RouteList, used to end a withDomain()/withPath() chain.
+	 */
 	public function end(): ?self
 	{
 		return $this->parent;
 	}
 
 
 	/**
+	 * Returns all routers in this list.
 	 * @return list<Router>
 	 */
 	public function getRouters(): array
@@ -284,6 +292,7 @@ public function getRouters(): array
 
 
 	/**
+	 * Returns the flags (e.g. ONE_WAY) for each router in this list.
 	 * @return list<int>
 	 */
 	public function getFlags(): array

src/Routing/Router.php

@@ -11,21 +11,21 @@
 
 
 /**
- * The bi-directional router.
+ * Bidirectional router converting between HTTP requests and parameter arrays.
  */
 interface Router
 {
-	/** for back compatibility */
+	/** @deprecated for backward compatibility */
 	public const ONE_WAY = 0b0001;
 
 	/**
-	 * Maps HTTP request to an array.
+	 * Matches an HTTP request and returns its parameters, or null if the route does not match.
 	 * @return ?array<string, mixed>
 	 */
 	function match(Nette\Http\IRequest $httpRequest): ?array;
 
 	/**
-	 * Constructs absolute URL from array.
+	 * Constructs an absolute URL from parameters, or null if the route cannot generate it.
 	 * @param array<string, mixed>  $params
 	 */
 	function constructUrl(array $params, Nette\Http\UrlScript $refUrl): ?string;

src/Routing/SimpleRouter.php

@@ -23,10 +23,7 @@ public function __construct(
 	}
 
 
-	/**
-	 * Maps HTTP request to an array.
-	 * @return ?array<string, mixed>
-	 */
+	/** @return ?array<string, mixed> */
 	public function match(Nette\Http\IRequest $httpRequest): ?array
 	{
 		return $httpRequest->getUrl()->getPathInfo() === ''
@@ -35,10 +32,7 @@ public function match(Nette\Http\IRequest $httpRequest): ?array
 	}
 
 
-	/**
-	 * Constructs absolute URL from array.
-	 * @param array<string, mixed>  $params
-	 */
+	/** @param array<string, mixed>  $params */
 	public function constructUrl(array $params, Nette\Http\UrlScript $refUrl): ?string
 	{
 		// remove default values; null values are retain
@@ -61,10 +55,7 @@ public function constructUrl(array $params, Nette\Http\UrlScript $refUrl): ?stri
 	}
 
 
-	/**
-	 * Returns default values.
-	 * @return array<string, mixed>
-	 */
+	/** @return array<string, mixed> */
 	public function getDefaults(): array
 	{
 		return $this->defaults;