(Changed) Update PHPDoc and Code Comments for Better Clarity and Update .pr_agent.toml Configuration

.pr_agent.toml

@@ -4,7 +4,7 @@ ask_and_reflect = true
 automatic_review = true
 remove_previous_review_comment = true
 persistent_comment = true
-extra_instructions = ""
+extra_instructions = "Please ensure comments are concise and actionable."
 enable_review_labels_security = true
 enable_review_labels_effort = true
 require_all_thresholds_for_incremental_review = false
@@ -15,10 +15,14 @@ enable_auto_approval = true
 maximal_review_effort = 5
 
 [pr_code_suggestions]
+num_code_suggestions = 5
 summarize = true
+auto_extended_mode = true
+rank_suggestions = true
+enable_help_text = false
 
 [pr_update_changelog]
-push_changelog_changes=false
+push_changelog_changes = false
 
 [github_action_config]
 auto_review = true
@@ -29,13 +33,13 @@ auto_improve = true
 pr_commands = [
     "/describe --pr_description.add_original_user_description=true --pr_description.keep_original_user_title=true",
     "/update_changelog --pr_update_changelog.push_changelog_changes=false",
-    "/improve --pr_code_suggestions.summarize=true",
+    "/improve --extended --pr_code_suggestions.summarize=true",
     "/review auto_approve --pr_reviewer.num_code_suggestions=0 --pr_reviewer.inline_code_comments=true",
 ]
 push_commands = [
     "/describe --pr_description.add_original_user_description=true --pr_description.keep_original_user_title=true",
     "/update_changelog --pr_update_changelog.push_changelog_changes=false",
-    "/improve --pr_code_suggestions.summarize=true",
+    "/improve --extended --pr_code_suggestions.summarize=true",
     """/auto_review -i \
        --pr_reviewer.require_focused_review=false \
        --pr_reviewer.require_score_review=false \
@@ -51,3 +55,4 @@ push_commands = [
     """,
     "/review auto_approve --pr_reviewer.num_code_suggestions=0 --pr_reviewer.inline_code_comments=true"
 ]
+handle_push_trigger = true

src/StringManipulation.php

@@ -10,21 +10,22 @@
 /**
  * Class StringManipulation.
  *
- * This class provides a collection of static methods for various string operations.
- * These operations include, but are not limited to:
- * - String transformation: Changing the format or structure of a string.
- * - Accent removal: Removing accents from characters within a string.
- * - String replacement: Replacing certain substrings within a string with other substrings.
- * - Date validation: Checking if a given date string is valid according to a specified format.
+ * This class offers a comprehensive suite of static methods for a variety of string operations,
+ * making it an indispensable resource for tasks involving string manipulation or validation. Utilising a blend of
+ * advanced algorithms and efficient coding practices.
+ * Operations include:
+ * - String transformation: Modifying the format or structure of a string.
+ * - Accent removal: Eliminating accents from characters within a string.
+ * - String replacement: Substituting specific substrings within a string with alternative substrings.
+ * - Date validation: Verifying the validity of a given date string against a specified format.
  *
- * Each method in this class is designed to perform a specific operation and can be used independently of the others.
- * This makes the class a versatile tool for any tasks involving string manipulation or validation.
+ * Each method within this class is meticulously crafted to execute a distinct operation,
+ * allowing for their independent utilisation. This attribute renders the class a versatile
+ * tool for any string manipulation or validation endeavours.
  *
- * Note: This class is suppressed from UnusedClass warning from Psalm static analysis tool.
- * It means that
- * the class is not directly instantiated or invoked in the codebase.
- * However, it is intended to be used
- * wherever necessary, hence the suppression.
+ * Note: This class is exempt from the UnusedClass warning by the Psalm static analysis tool,
+ * indicating that while it may not be directly instantiated or invoked within the codebase,
+ * it is designed for use wherever necessary, thus justifying the exemption.
  *
  * @psalm-suppress UnusedClass
  */
@@ -40,7 +41,7 @@ class StringManipulation
      * This function performs several transformations on the input string to make it suitable for
      * searching within a database. The transformations include:
      * - Applying the name fixing standards via the `nameFix` function. (Refer to its PHPDoc for details.)
-     * - Converting the string to lowercase.
+     * - Converting the string to lower case using `strtolower`.
      * - Replacing various special characters with spaces (e.g., '{', '}', '(', ')', etc.).
      * - Replacing underscores with spaces.
      * - Removing accents from characters.
@@ -236,26 +237,28 @@ public static function removeAccents(string $str): string
 
 
     /**
-     * Replace all occurrences of the search string(s) with the corresponding replacement string(s) in the subject.
+     * Replaces all occurrences of the search string(s) with the corresponding replacement string(s) in the subject.
      *
-     * This function is a stricter version of the built-in PHP str_replace function. It takes three parameters:
-     * - $search: The value(s) being searched for in the subject. This can be a single string or an array of strings.
-     * - $replace: The replacement value(s) to replace found search values. This can be a single string or an array of
+     * This method acts as a more precise version of the built-in PHP str_replace function. It accepts three
+     * parameters:
+     * - $search: The value(s) being searched for within the subject. This can be a single string or an array of
      * strings.
-     * - $subject: The string being searched and replaced on.
+     * - $replace: The replacement value(s) for the found search values. This can be a single string or an array of
+     * strings.
+     * - $subject: The string within which the search and replacement is to be performed.
      *
-     * The function returns a new string where all occurrences of each search value have been replaced by the
+     * It returns a new string wherein every occurrence of each search value has been substituted with the
      * corresponding replacement value.
      *
-     * This function is useful when you need to replace multiple different substrings within a string, or when you need
-     * to perform the same set of replacements on multiple strings.
+     * This method is particularly useful for replacing multiple distinct substrings within a string, or when the same
+     * set of replacements needs to be applied across multiple strings.
      *
-     * @param string|string[] $search The value(s) being searched for in the subject.
-     * @param string|string[] $replace The replacement value(s) to replace found search values.
-     * @param string $subject The string being searched and replaced on.
+     * @param string|string[] $search The value(s) being searched for within the subject.
+     * @param string|string[] $replace The replacement value(s) for the found search values.
+     * @param string $subject The string within which the search and replacement are to be performed.
      *
-     * @return string Returns a string where all occurrences of each search value have been replaced by the
-     *                corresponding replacement value.
+     * @return string A string where every occurrence of each search value has been substituted with the corresponding
+     *     replacement value.
      *
      * @psalm-suppress PossiblyUnusedMethod,UnusedParam
      */