improved phpDoc

Author: dg

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

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<Name> method.
+	 * Creates a new component. Delegates creation to createComponent<Name> 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<int|string,IComponent>
 	 */
 	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()
 	{

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;
 }

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
 {