improved PHPDoc descriptions

dg · dg · commit 88cb02f9e6c0 · 2026-03-09T06:04:10.000+01:00
diff --git a/src/Assets/Asset.php b/src/Assets/Asset.php
@@ -4,7 +4,7 @@
 
 
 /**
- * Base asset interface with minimal API.
+ * Represents a web asset (image, script, stylesheet, font, etc.).
  * @property-read string $url The public URL
  * @property-read ?string $file The local file path if available
  */
@@ -14,7 +14,7 @@ interface Asset
 	//public ?string $file { get; }
 
 	/**
-	 * Allows direct echoing of the object to get the URL.
+	 * Returns the asset URL.
 	 */
 	public function __toString(): string;
 }
diff --git a/src/Assets/AudioAsset.php b/src/Assets/AudioAsset.php
@@ -6,7 +6,7 @@
 
 
 /**
- * Audio asset.
+ * Audio file with lazy-loaded duration.
  */
 class AudioAsset implements Asset, HtmlRenderable
 {
diff --git a/src/Assets/EntryAsset.php b/src/Assets/EntryAsset.php
@@ -4,7 +4,7 @@
 
 
 /**
- * Entry point asset implementation that can represent both script and style entry points.
+ * Vite entry point asset that carries its CSS imports and JS preloads as dependencies.
  */
 class EntryAsset extends ScriptAsset
 {
diff --git a/src/Assets/FilesystemMapper.php b/src/Assets/FilesystemMapper.php
@@ -25,9 +25,9 @@ public function __construct(
 
 
 	/**
-	 * Resolves a relative reference to an asset within the configured base path.
-	 * Attempts to find a matching extension if configured and applies versioning if enabled.
-	 * Available options: 'version' => bool: Whether to apply versioning (defaults to true)
+	 * Returns the asset for the given relative reference.
+	 * Tries configured extensions in order and appends a version query parameter if enabled.
+	 * Supported option: 'version' => bool (overrides the mapper-level versioning setting)
 	 */
 	public function getAsset(string $reference, array $options = []): Asset
 	{
@@ -47,6 +47,9 @@ public function getAsset(string $reference, array $options = []): Asset
 	}
 
 
+	/**
+	 * Appends a ?v={filemtime} (or &v={filemtime}) version parameter to the URL.
+	 */
 	protected function applyVersion(string $url, string $path): string
 	{
 		if (is_int($version = filemtime($path))) {
@@ -57,7 +60,7 @@ protected function applyVersion(string $url, string $path): string
 
 
 	/**
-	 * Searches for an existing file by appending configured extensions to the base path.
+	 * Returns the first matching file extension (with dot) from the configured list, or '' if none match.
 	 */
 	private function findExtension(string $basePath): string
 	{
@@ -78,18 +81,12 @@ private function findExtension(string $basePath): string
 	}
 
 
-	/**
-	 * Returns the base URL for this mapper.
-	 */
 	public function getBaseUrl(): string
 	{
 		return $this->baseUrl;
 	}
 
 
-	/**
-	 * Returns the base path for this mapper.
-	 */
 	public function getBasePath(): string
 	{
 		return $this->basePath;
diff --git a/src/Assets/FontAsset.php b/src/Assets/FontAsset.php
@@ -6,7 +6,7 @@
 
 
 /**
- * Font asset.
+ * Web font file (WOFF, WOFF2, TTF, etc.).
  */
 class FontAsset implements Asset, HtmlRenderable
 {
diff --git a/src/Assets/GenericAsset.php b/src/Assets/GenericAsset.php
@@ -4,7 +4,7 @@
 
 
 /**
- * Generic asset for any general file type.
+ * Asset for file types without a dedicated asset class.
  */
 class GenericAsset implements Asset
 {
diff --git a/src/Assets/Helpers.php b/src/Assets/Helpers.php
@@ -7,7 +7,7 @@
 
 
 /**
- * Static helper class providing utility functions for working with assets.
+ * Asset utility functions.
  */
 final class Helpers
 {
@@ -24,9 +24,10 @@ final class Helpers
 
 
 	/**
-	 * Creates an Asset instance. The asset type is detected by 'mimeType' if provided in $args,
-	 * otherwise is guessed from the file extension of $path or $url.
-	 * @param  array<string, mixed>  $args parameters passed to the asset constructor
+	 * Creates an Asset of the appropriate type for the given URL.
+	 * The type is determined from the 'mimeType' key in $args if provided,
+	 * otherwise guessed from the file extension of $path or $url.
+	 * @param  array<string, mixed>  $args  additional constructor arguments for the asset
 	 */
 	public static function createAssetFromUrl(string $url, ?string $path = null, array $args = []): Asset
 	{
@@ -47,6 +48,9 @@ public static function createAssetFromUrl(string $url, ?string $path = null, arr
 	}
 
 
+	/**
+	 * Guesses the MIME type from the file extension in the given URL or path, or null if unknown.
+	 */
 	public static function guessMimeTypeFromExtension(string $url): ?string
 	{
 		return preg_match('~\.([a-z0-9]{1,5})([?#]|$)~i', $url, $m)
@@ -120,6 +124,9 @@ public static function guessMP3Duration(string $path): float
 	}
 
 
+	/**
+	 * Reads the Vite dev server URL from the given info file, or returns null if unavailable.
+	 */
 	public static function detectDevServer(string $infoFile): ?string
 	{
 		return ($info = @file_get_contents($infoFile)) // @ file may not exists
diff --git a/src/Assets/HtmlRenderable.php b/src/Assets/HtmlRenderable.php
@@ -6,17 +6,17 @@
 
 
 /**
- * Interface for assets that can be rendered as HTML elements.
+ * Asset renderable as an HTML element.
  */
 interface HtmlRenderable extends Asset
 {
 	/**
-	 * Returns HTML tag name and attributes for rendering the asset.
+	 * Returns the HTML element used to import the asset (img, script, link rel="stylesheet", etc.).
 	 */
 	public function getImportElement(): Html;
 
 	/**
-	 * Returns HTML tag name and attributes for preloading the asset.
+	 * Returns the HTML element used to preload the asset (link rel="preload" or rel="modulepreload").
 	 */
 	public function getPreloadElement(): Html;
 }
diff --git a/src/Assets/ImageAsset.php b/src/Assets/ImageAsset.php
@@ -7,7 +7,7 @@
 
 
 /**
- * Image asset.
+ * Image file with lazy-loaded dimensions and MIME type.
  */
 class ImageAsset implements Asset, HtmlRenderable
 {
diff --git a/src/Assets/Mapper.php b/src/Assets/Mapper.php
@@ -4,14 +4,13 @@
 
 
 /**
- * Defines the contract for resolving asset references to Asset objects.
- * Implementations handle specific storage backends (filesystem, CDN, etc.).
+ * Resolves asset references to Asset objects for a specific storage backend.
  */
 interface Mapper
 {
 	/**
-	 * Retrieves an Asset instance for a given mapper-specific reference string.
-	 * @param  array<string, mixed>  $options mapper-specific options
+	 * Returns an Asset for the given reference.
+	 * @param  array<string, mixed>  $options  mapper-specific options
 	 * @throws AssetNotFoundException when the asset cannot be found
 	 */
 	public function getAsset(string $reference, array $options = []): Asset;
diff --git a/src/Assets/Registry.php b/src/Assets/Registry.php
@@ -6,9 +6,8 @@
 
 
 /**
- * Manages a collection of named asset Mappers and provides a central point
- * for retrieving Assets using qualified references (mapper:reference).
- * Includes a simple cache for resolved assets.
+ * Central registry of named asset mappers with LRU cache.
+ * Resolves qualified references in the form 'mapper:reference' or ['mapper', 'reference'].
  */
 class Registry
 {
@@ -23,8 +22,8 @@ class Registry
 
 
 	/**
-	 * Registers a new asset mapper under a specific identifier.
-	 * @throws \InvalidArgumentException If the identifier is already in use.
+	 * Registers an asset mapper under the given identifier.
+	 * @throws \InvalidArgumentException if the identifier is already in use
 	 */
 	public function addMapper(string $id, Mapper $mapper): void
 	{
@@ -36,8 +35,8 @@ public function addMapper(string $id, Mapper $mapper): void
 
 
 	/**
-	 * Retrieves a registered asset mapper by its identifier.
-	 * @throws \InvalidArgumentException If the requested mapper identifier is unknown.
+	 * Returns the mapper registered under the given identifier.
+	 * @throws \InvalidArgumentException if the identifier is unknown
 	 */
 	public function getMapper(string $id = self::DefaultScope): Mapper
 	{
@@ -46,10 +45,9 @@ public function getMapper(string $id = self::DefaultScope): Mapper
 
 
 	/**
-	 * Retrieves an Asset instance using a qualified reference. Accepts either 'mapper:reference' or ['mapper', 'reference'].
-	 * Options passed directly to the underlying Mapper::getAsset() method.
+	 * Returns an Asset for the given qualified reference ('mapper:reference' or ['mapper', 'reference']).
 	 * @param  string|array{?string, string}  $qualifiedRef
-	 * @param  array<string, mixed>  $options
+	 * @param  array<string, mixed>  $options  passed to the mapper
 	 * @throws AssetNotFoundException when the asset cannot be found
 	 */
 	public function getAsset(string|array $qualifiedRef, array $options = []): Asset
@@ -84,11 +82,9 @@ public function getAsset(string|array $qualifiedRef, array $options = []): Asset
 
 
 	/**
-	 * Attempts to retrieve an Asset instance using a qualified reference, but returns null if not found.
-	 * Accepts either 'mapper:reference' or ['mapper', 'reference'].
-	 * Options passed directly to the underlying Mapper::getAsset() method.
+	 * Returns an Asset for the given qualified reference, or null if not found.
 	 * @param  string|array{string|null, string}  $qualifiedRef
-	 * @param  array<string, mixed>  $options
+	 * @param  array<string, mixed>  $options  passed to the mapper
 	 */
 	public function tryGetAsset(string|array $qualifiedRef, array $options = []): ?Asset
 	{
@@ -101,7 +97,8 @@ public function tryGetAsset(string|array $qualifiedRef, array $options = []): ?A
 
 
 	/**
-	 * @param array<string, mixed>  $options
+	 * Returns null when options contain non-scalar values (caching is disabled for such options).
+	 * @param  array<string, mixed>  $options
 	 */
 	private function generateCacheKey(string $mapper, string $reference, array $options): ?string
 	{
diff --git a/src/Assets/ScriptAsset.php b/src/Assets/ScriptAsset.php
@@ -6,7 +6,7 @@
 
 
 /**
- * Script asset.
+ * JavaScript file.
  */
 class ScriptAsset implements Asset, HtmlRenderable
 {
diff --git a/src/Assets/StyleAsset.php b/src/Assets/StyleAsset.php
@@ -6,7 +6,7 @@
 
 
 /**
- * Style asset.
+ * CSS stylesheet file.
  */
 class StyleAsset implements Asset, HtmlRenderable
 {
diff --git a/src/Assets/VideoAsset.php b/src/Assets/VideoAsset.php
@@ -6,7 +6,7 @@
 
 
 /**
- * Video asset.
+ * Video file.
  */
 class VideoAsset implements Asset, HtmlRenderable
 {
diff --git a/src/Assets/ViteMapper.php b/src/Assets/ViteMapper.php
@@ -16,7 +16,7 @@ class ViteMapper implements Mapper
 	/** @var array<string, array{file: string, isEntry?: bool, isDynamicEntry?: bool, css?: list<string>, imports?: list<string>}> */
 	private array $chunks;
 
-	/** @var array<string, ?array<string, Asset>> cached dependencies keyed by chunkId */
+	/** @var array<string, ?array<string, Asset>> dependencies cache keyed by chunk ID; null = not yet computed */
 	private array $dependencies = [];
 
 
@@ -34,8 +34,8 @@ public function __construct(
 
 
 	/**
-	 * Retrieves an Asset for a given Vite entry point.
-	 * @throws AssetNotFoundException when the asset cannot be found in the manifest
+	 * Returns an Asset for the given Vite entry point or public directory file.
+	 * @throws AssetNotFoundException when the asset is not found in the manifest or public directory
 	 */
 	public function getAsset(string $reference, array $options = []): Asset
 	{
@@ -149,18 +149,12 @@ private function readChunks(): array
 	}
 
 
-	/**
-	 * Returns the base URL for this mapper.
-	 */
 	public function getBaseUrl(): string
 	{
 		return $this->baseUrl;
 	}
 
 
-	/**
-	 * Returns the base path for this mapper.
-	 */
 	public function getBasePath(): string
 	{
 		return $this->basePath;
diff --git a/src/Assets/exceptions.php b/src/Assets/exceptions.php
@@ -8,7 +8,10 @@
  */
 class AssetNotFoundException extends \Exception
 {
-	/** @internal */
+	/**
+	 * Prepends the mapper prefix to the reference in the exception message.
+	 * @internal
+	 */
 	public function qualifyReference(string $mapper, string $reference): self
 	{
 		if ($mapper !== '') {
diff --git a/src/Bridges/AssetsDI/DIExtension.php b/src/Bridges/AssetsDI/DIExtension.php
@@ -13,8 +13,7 @@
 
 
 /**
- * Dependency injection extension that integrates asset management into Nette application.
- * Provides configuration of asset mappers and their mapping to URL paths.
+ * Nette DI extension that registers asset mappers and the asset Registry as container services.
  */
 final class DIExtension extends Nette\DI\CompilerExtension
 {
diff --git a/src/Bridges/AssetsLatte/Nodes/NAssetNode.php b/src/Bridges/AssetsLatte/Nodes/NAssetNode.php
@@ -86,6 +86,7 @@ private function init(Tag $tag): void
 
 
 	/**
+	 * Collects attributes explicitly set on the HTML element, mapping name to value or true.
 	 * @internal
 	 * @return array<string, string|true>
 	 */
diff --git a/src/Bridges/AssetsLatte/Runtime.php b/src/Bridges/AssetsLatte/Runtime.php

Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@`
`6`	`6`
`7`	`7`
`8`	`8`	`/**`
`9`		`- * Audio asset.`
	`9`	`+ * Audio file with lazy-loaded duration.`
`10`	`10`	`*/`
`11`	`11`	`class AudioAsset implements Asset, HtmlRenderable`
`12`	`12`	`{`
Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@`
`4`	`4`
`5`	`5`
`6`	`6`	`/**`
`7`		`- * Entry point asset implementation that can represent both script and style entry points.`
	`7`	`+ * Vite entry point asset that carries its CSS imports and JS preloads as dependencies.`
`8`	`8`	`*/`
`9`	`9`	`class EntryAsset extends ScriptAsset`
`10`	`10`	`{`
Original file line number	Diff line number	Diff line change
`@@ -25,9 +25,9 @@ public function __construct(`
`25`	`25`
`26`	`26`
`27`	`27`	`/**`
`28`		`- * Resolves a relative reference to an asset within the configured base path.`
`29`		`- * Attempts to find a matching extension if configured and applies versioning if enabled.`
`30`		`- * Available options: 'version' => bool: Whether to apply versioning (defaults to true)`
	`28`	`+ * Returns the asset for the given relative reference.`
	`29`	`+ * Tries configured extensions in order and appends a version query parameter if enabled.`
	`30`	`+ * Supported option: 'version' => bool (overrides the mapper-level versioning setting)`
`31`	`31`	`*/`
`32`	`32`	`public function getAsset(string $reference, array $options = []): Asset`
`33`	`33`	`{`
`@@ -47,6 +47,9 @@ public function getAsset(string $reference, array $options = []): Asset`
`47`	`47`	`}`
`48`	`48`
`49`	`49`
	`50`	`+ /**`
	`51`	`+ * Appends a ?v={filemtime} (or &v={filemtime}) version parameter to the URL.`
	`52`	`+ */`
`50`	`53`	`protected function applyVersion(string $url, string $path): string`
`51`	`54`	`{`
`52`	`55`	`if (is_int($version = filemtime($path))) {`
`@@ -57,7 +60,7 @@ protected function applyVersion(string $url, string $path): string`
`57`	`60`
`58`	`61`
`59`	`62`	`/**`
`60`		`- * Searches for an existing file by appending configured extensions to the base path.`
	`63`	`+ * Returns the first matching file extension (with dot) from the configured list, or '' if none match.`
`61`	`64`	`*/`
`62`	`65`	`private function findExtension(string $basePath): string`
`63`	`66`	`{`
`@@ -78,18 +81,12 @@ private function findExtension(string $basePath): string`
`78`	`81`	`}`
`79`	`82`
`80`	`83`
`81`		`- /**`
`82`		`- * Returns the base URL for this mapper.`
`83`		`- */`
`84`	`84`	`public function getBaseUrl(): string`
`85`	`85`	`{`
`86`	`86`	`return $this->baseUrl;`
`87`	`87`	`}`
`88`	`88`
`89`	`89`
`90`		`- /**`
`91`		`- * Returns the base path for this mapper.`
`92`		`- */`
`93`	`90`	`public function getBasePath(): string`
`94`	`91`	`{`
`95`	`92`	`return $this->basePath;`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@`
`6`	`6`
`7`	`7`
`8`	`8`	`/**`
`9`		`- * Font asset.`
	`9`	`+ * Web font file (WOFF, WOFF2, TTF, etc.).`
`10`	`10`	`*/`
`11`	`11`	`class FontAsset implements Asset, HtmlRenderable`
`12`	`12`	`{`
Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@`
`4`	`4`
`5`	`5`
`6`	`6`	`/**`
`7`		`- * Generic asset for any general file type.`
	`7`	`+ * Asset for file types without a dedicated asset class.`
`8`	`8`	`*/`
`9`	`9`	`class GenericAsset implements Asset`
`10`	`10`	`{`
Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@`
`7`	`7`
`8`	`8`
`9`	`9`	`/**`
`10`		`- * Static helper class providing utility functions for working with assets.`
	`10`	`+ * Asset utility functions.`
`11`	`11`	`*/`
`12`	`12`	`final class Helpers`
`13`	`13`	`{`
`@@ -24,9 +24,10 @@ final class Helpers`
`24`	`24`
`25`	`25`
`26`	`26`	`/**`
`27`		`- * Creates an Asset instance. The asset type is detected by 'mimeType' if provided in $args,`
`28`		`- * otherwise is guessed from the file extension of $path or $url.`
`29`		`- * @param array<string, mixed> $args parameters passed to the asset constructor`
	`27`	`+ * Creates an Asset of the appropriate type for the given URL.`
	`28`	`+ * The type is determined from the 'mimeType' key in $args if provided,`
	`29`	`+ * otherwise guessed from the file extension of $path or $url.`
	`30`	`+ * @param array<string, mixed> $args additional constructor arguments for the asset`
`30`	`31`	`*/`
`31`	`32`	`public static function createAssetFromUrl(string $url, ?string $path = null, array $args = []): Asset`
`32`	`33`	`{`
`@@ -47,6 +48,9 @@ public static function createAssetFromUrl(string $url, ?string $path = null, arr`
`47`	`48`	`}`
`48`	`49`
`49`	`50`
	`51`	`+ /**`
	`52`	`+ * Guesses the MIME type from the file extension in the given URL or path, or null if unknown.`
	`53`	`+ */`
`50`	`54`	`public static function guessMimeTypeFromExtension(string $url): ?string`
`51`	`55`	`{`
`52`	`56`	`return preg_match('~\.([a-z0-9]{1,5})([?#]\|$)~i', $url, $m)`
`@@ -120,6 +124,9 @@ public static function guessMP3Duration(string $path): float`
`120`	`124`	`}`
`121`	`125`
`122`	`126`
	`127`	`+ /**`
	`128`	`+ * Reads the Vite dev server URL from the given info file, or returns null if unavailable.`
	`129`	`+ */`
`123`	`130`	`public static function detectDevServer(string $infoFile): ?string`
`124`	`131`	`{`
`125`	`132`	`return ($info = @file_get_contents($infoFile)) // @ file may not exists`