Node doc

src/DataNodeContract.php

@@ -22,7 +22,7 @@ interface DataNodeContract
     public function data(): mixed;
 
     /**
-     * Set/assign new data to the node.
+     * Set/assign new data to the data node.
      */
     public function fill(mixed $data): self;
 }

src/Node.php

@@ -23,16 +23,27 @@ public function __construct(
     ) {
     }
 
+    /**
+     * Get the node's parent, if any.
+     */
     public function parent(): ?TreeNodeContract
     {
         return $this->parent;
     }
 
+    /**
+     * Get the node's children.
+     *
+     * @return iterable<int|string,TreeNodeContract>
+     */
     public function children(): array
     {
         return $this->children;
     }
 
+    /**
+     * Discover whether the given node is one or the given key points to one of this node's children.
+     */
     public function hasChild(TreeNodeContract|string|int $child): bool
     {
         if (is_scalar($child)) {
@@ -45,11 +56,19 @@ public function hasChild(TreeNodeContract|string|int $child): bool
         return null !== $child && null !== $key;
     }
 
+    /**
+     * Get a specific child, if possible.
+     * Returns `null` when there is no such a child.
+     */
     public function child(int|string $key): ?TreeNodeContract
     {
         return $this->children[$key] ?? null;
     }
 
+    /**
+     * Get a child's key (index), if possible.
+     * Returns `null` when the node is not a child.
+     */
     public function childKey(TreeNodeContract $node): string|int|null
     {
         foreach ($this->children as $key => $child) {
@@ -60,16 +79,26 @@ public function childKey(TreeNodeContract $node): string|int|null
         return null;
     }
 
+    /**
+     * Returns `true` if the node has no children, i.e. it is a leaf node.
+     */
     public function isLeaf(): bool
     {
         return count($this->children) === 0;
     }
 
+    /**
+     * Returns `true` if the node has no parent, i.e. it is a root node.
+     */
     public function isRoot(): bool
     {
         return null === $this->parent;
     }
 
+    /**
+     * Get the root node.
+     * May be self.
+     */
     public function root(): TreeNodeContract
     {
         $root = $this;
@@ -79,23 +108,41 @@ public function root(): TreeNodeContract
         return $root;
     }
 
+    /**
+     * Get the node's assigned data.
+     */
     public function data(): mixed
     {
         return $this->data;
     }
 
+    /**
+     * Set/assign new data to the data node.
+     */
     public function fill(mixed $data): self
     {
         $this->data = $data;
         return $this;
     }
 
+    /**
+     * Set the parent node.
+     *
+     * Does NOT alter the new parent node, nor the original parent node.
+     * Namely, the call does NOT alter the lists of children.
+     */
     public function setParent(?TreeNodeContract $parent): self
     {
         $this->parent = $parent;
         return $this;
     }
 
+    /**
+     * Add a node to the children list,
+     * optionally specifying its key (index).
+     *
+     * Does NOT set the parent on the child node.
+     */
     public function addChild(TreeNodeContract $child, string|int|null $key = null): self
     {
         if (null === $key) {
@@ -108,6 +155,11 @@ public function addChild(TreeNodeContract $child, string|int|null $key = null):
         return $this;
     }
 
+    /**
+     * Remove a specific child from the list of children.
+     *
+     * Does NOT unset the parent of the child being removed.
+     */
     public function removeChild(TreeNodeContract|string|int $child): self
     {
         $key = is_scalar($child) ? $child : $this->childKey($child);
@@ -117,12 +169,21 @@ public function removeChild(TreeNodeContract|string|int $child): self
         return $this;
     }
 
+    /**
+     * Remove all children.
+     *
+     * Does NOT unset the parent of the children nodes being removed.
+     */
     public function removeChildren(): self
     {
         $this->children = [];
         return $this;
     }
 
+    /**
+     * Returns an iterator that iterates over this node and all its descendants in pre-order depth-first search order.
+     * @return PreOrderTraversal
+     */
     public function getIterator(): PreOrderTraversal
     {
         return new PreOrderTraversal($this);

src/TreeNodeContract.php

@@ -23,6 +23,11 @@ public function parent(): ?TreeNodeContract;
      */
     public function children(): iterable;
 
+    /**
+     * Discover whether the given node is one or the given key points to one of this node's children.
+     */
+    public function hasChild(TreeNodeContract|string|int $child): bool;
+
     /**
      * Get a specific child, if possible.
      * Returns `null` when there is no such a child.
@@ -35,11 +40,6 @@ public function child(string|int $key): ?TreeNodeContract;
      */
     public function childKey(TreeNodeContract $node): string|int|null;
 
-    /**
-     * Discover whether the given node is one or the given key points to one of this node's children.
-     */
-    public function hasChild(TreeNodeContract|string|int $child): bool;
-
     /**
      * Returns `true` if the node has no children, i.e. it is a leaf node.
      */