From fb7608fd5f1c378ef9ef8ddc459c6ef0b63e9d77 Mon Sep 17 00:00:00 2001 From: David Grudl Date: Wed, 7 Aug 2024 02:35:59 +0200 Subject: [PATCH] improved phpDoc --- src/ComponentModel/Component.php | 14 ++++++-------- src/ComponentModel/Container.php | 17 +++++++++-------- src/ComponentModel/IComponent.php | 4 ++-- src/ComponentModel/IContainer.php | 2 +- 4 files changed, 18 insertions(+), 19 deletions(-) diff --git a/src/ComponentModel/Component.php b/src/ComponentModel/Component.php index 492e452..64f77fc 100644 --- a/src/ComponentModel/Component.php +++ b/src/ComponentModel/Component.php @@ -13,9 +13,7 @@ /** - * Component is the base class for all components. - * - * Components are objects implementing IComponent. They has parent component and own name. + * Base class for all components. Components have a parent, name, and can be monitored by ancestors. * * @property-read string $name * @property-read IContainer|null $parent @@ -32,7 +30,7 @@ abstract class Component implements IComponent /** - * Finds the closest ancestor specified by class or interface name. + * Finds the closest ancestor of specified type. * @param bool $throw throw exception if component doesn't exist? * @return ($throw is true ? IComponent : ?IComponent) */ @@ -88,7 +86,7 @@ final public function lookupPath(?string $type = null, bool $throw = true): ?str /** - * Starts monitoring of ancestors. + * Starts monitoring ancestors for attach/detach events. */ final public function monitor(string $type, ?callable $attached = null, ?callable $detached = null): void { @@ -110,7 +108,7 @@ final public function monitor(string $type, ?callable $attached = null, ?callabl /** - * Stops monitoring of ancestors. + * Stops monitoring ancestors of specified type. */ final public function unmonitor(string $type): void { @@ -198,8 +196,8 @@ public function setParent(?IContainer $parent, ?string $name = null): static /** - * Is called by a component when it is about to be set new parent. Descendant can - * override this method to disallow a parent change by throwing an Nette\InvalidStateException + * Validates the new parent before it's set. + * Descendant classes can override this to implement custom validation logic. * @throws Nette\InvalidStateException */ protected function validateParent(IContainer $parent): void diff --git a/src/ComponentModel/Container.php b/src/ComponentModel/Container.php index ec74fa1..256196f 100644 --- a/src/ComponentModel/Container.php +++ b/src/ComponentModel/Container.php @@ -13,7 +13,7 @@ /** - * ComponentContainer is default implementation of IContainer. + * Manages a collection of child components. * * @property-read IComponent[] $components */ @@ -30,7 +30,7 @@ class Container extends Component implements IContainer /** - * Adds the component to the container. + * Adds a child component to the container. * @return static * @throws Nette\InvalidStateException */ @@ -91,7 +91,7 @@ public function addComponent(IComponent $component, ?string $name, ?string $inse /** - * Removes the component from the container. + * Removes a child component from the container. */ public function removeComponent(IComponent $component): void { @@ -106,7 +106,7 @@ public function removeComponent(IComponent $component): void /** - * Returns component specified by name or path. + * Retrieves a child component by name or creates it if it doesn't exist. * @param bool $throw throw exception if component doesn't exist? * @return ($throw is true ? IComponent : ?IComponent) */ @@ -153,7 +153,7 @@ final public function getComponent(string $name, bool $throw = true): ?IComponen /** - * Component factory. Delegates the creation of components to a createComponent method. + * Creates a new component. Delegates creation to createComponent method if it exists. */ protected function createComponent(string $name): ?IComponent { @@ -178,7 +178,7 @@ protected function createComponent(string $name): ?IComponent /** - * Returns immediate child components. + * Returns all immediate child components. * @return array */ final public function getComponents(): iterable @@ -217,7 +217,8 @@ final public function getComponentTree(): array /** - * Descendant can override this method to disallow insert a child by throwing an Nette\InvalidStateException. + * Validates a child component before it's added to the container. + * Descendant classes can override this to implement custom validation logic. * @throws Nette\InvalidStateException */ protected function validateChildComponent(IComponent $child): void @@ -229,7 +230,7 @@ protected function validateChildComponent(IComponent $child): void /** - * Object cloning. + * Handles object cloning. Clones all child components and re-sets their parents. */ public function __clone() { diff --git a/src/ComponentModel/IComponent.php b/src/ComponentModel/IComponent.php index eb21c97..4573a50 100644 --- a/src/ComponentModel/IComponent.php +++ b/src/ComponentModel/IComponent.php @@ -11,7 +11,7 @@ /** - * Provides functionality required by all components. + * Defines core functionality required by all components. */ interface IComponent { @@ -29,7 +29,7 @@ function getName(): ?string; function getParent(): ?IContainer; /** - * Sets the parent of this component. + * Sets the parent container and optionally renames the component. */ function setParent(?IContainer $parent, ?string $name = null): static; } diff --git a/src/ComponentModel/IContainer.php b/src/ComponentModel/IContainer.php index 12cfb84..18956ac 100644 --- a/src/ComponentModel/IContainer.php +++ b/src/ComponentModel/IContainer.php @@ -13,7 +13,7 @@ /** - * Containers are objects that logically contain zero or more IComponent components. + * Defines functionality for objects that can contain other components. */ interface IContainer extends IComponent {