From 95e15e9274161fb9c9dfaf863fd925f426d06b07 Mon Sep 17 00:00:00 2001
From: rudashi <rudashi@gmail.com>
Date: Thu, 9 May 2024 07:07:20 +0200
Subject: [PATCH] Added comments

---
 src/Anchors.php             | 32 ++++++++++++++++++++++++++++++++
 src/Concerns/HasAnchors.php | 32 ++++++++++++++++++++++++++++----
 2 files changed, 60 insertions(+), 4 deletions(-)

diff --git a/src/Anchors.php b/src/Anchors.php
index a12b5b6..2c7f065 100644
--- a/src/Anchors.php
+++ b/src/Anchors.php
@@ -9,21 +9,36 @@
 class Anchors
 {
     /**
+     * List of assigned starting anchors.
+     *
      * @var array<int, string>
      */
     protected array $prefix = [];
 
     /**
+     * List of assigned ending anchors.
+     *
      * @var array<int, string>
      */
     protected array $suffix = [];
 
+    /**
+     * Create an instance of Anchors.
+     *
+     * @param  \Rudashi\FluentBuilder  $builder
+     * @param  string  $delimiter
+     */
     public function __construct(
         private readonly FluentBuilder $builder,
         private readonly string $delimiter,
     ) {
     }
 
+    /**
+     * Adds a starting anchor.
+     *
+     * @return \Rudashi\FluentBuilder
+     */
     public function start(): FluentBuilder
     {
         if ($this->prefix !== []) {
@@ -35,6 +50,11 @@ public function start(): FluentBuilder
         return $this->builder;
     }
 
+    /**
+     * Adds an end anchor.
+     *
+     * @return \Rudashi\FluentBuilder
+     */
     public function end(): FluentBuilder
     {
         if ($this->suffix !== []) {
@@ -47,6 +67,8 @@ public function end(): FluentBuilder
     }
 
     /**
+     * Returns a list of starting anchors.
+     *
      * @return array<int, string>
      */
     public function getPrefix(): array
@@ -55,6 +77,8 @@ public function getPrefix(): array
     }
 
     /**
+     * Returns a list of ending anchors.
+     *
      * @return array<int, string>
      */
     public function getSuffix(): array
@@ -62,6 +86,14 @@ public function getSuffix(): array
         return [...$this->suffix, $this->delimiter];
     }
 
+    /**
+     * Throws a logical exception when the same flag is reused.
+     *
+     * @param  string  $method
+     * @return never
+     *
+     * @throws \LogicException
+     */
     protected function throwAnchorException(string $method): never
     {
         throw new LogicException(sprintf('The "%s" anchor has already been called.', $method));
diff --git a/src/Concerns/HasAnchors.php b/src/Concerns/HasAnchors.php
index f83fab0..9303753 100644
--- a/src/Concerns/HasAnchors.php
+++ b/src/Concerns/HasAnchors.php
@@ -4,24 +4,48 @@
 
 namespace Rudashi\Concerns;
 
+use Rudashi\FluentBuilder;
+
 trait HasAnchors
 {
-    public function start(): self
+    /**
+     * Adds the beginning of a string anchor.
+     * If multiline mode is used, this will also work after a newline character.
+     *
+     * @return \Rudashi\FluentBuilder
+     */
+    public function start(): FluentBuilder
     {
         return $this->anchors->start();
     }
 
-    public function startOfLine(): self
+    /**
+     * Alias for the `start` method.
+     *
+     * @return \Rudashi\FluentBuilder
+     */
+    public function startOfLine(): FluentBuilder
     {
         return $this->start();
     }
 
-    public function end(): self
+    /**
+     * Adds the end of a string anchor.
+     * If multiline mode is used, this will also work before a newline character.
+     *
+     * @return \Rudashi\FluentBuilder
+     */
+    public function end(): FluentBuilder
     {
         return $this->anchors->end();
     }
 
-    public function endOfLine(): self
+    /**
+     * Alias for the `end` method.
+     *
+     * @return \Rudashi\FluentBuilder
+     */
+    public function endOfLine(): FluentBuilder
     {
         return $this->end();
     }