gpt: Automated pattern documentation updates

Author: nicklem

docs/description/CakePHP_Classes_ReturnTypeHint.md

@@ -1 +1,10 @@
-Classes: Return Type Hint
+Validates that return types are properly hinted in CakePHP classes. This improves code readability and reduces runtime errors. For example:
+
+```php
+public function getName(): string {
+    return $this->name;
+}
+```
+Ensures `getName` returns a string.
+
+<!-- Codacy PatPatBot reviewed: 2024-05-23T15:33:40.325Z -->

docs/description/CakePHP_Commenting_DocBlockAlignment.md

@@ -1 +1,11 @@
-Commenting: Doc Block Alignment
+DocBlock comments should be properly aligned to enhance readability and consistency in CakePHP codebases. Ensure each line of the DocBlock starts evenly, maintaining the structure and alignment guidelines provided. For example:
+```php
+/**
+ * This is a sample DocBlock.
+ *
+ * @param string $example Description of parameter.
+ * @return void
+ */
+```
+
+<!-- Codacy PatPatBot reviewed: 2024-05-23T15:33:51.613Z -->

docs/description/CakePHP_Commenting_FunctionComment.md

@@ -1 +1,16 @@
-Commenting: Function Comment
+Ensure all functions in CakePHP are documented using PHPDoc comments for clarity and maintainability. Proper documentation helps in understanding the function's purpose, parameters, and return types. These comments can be used by IDEs for better code completion.
+
+```php
+/**
+ * Adds two numbers.
+ *
+ * @param int $a First number.
+ * @param int $b Second number.
+ * @return int Sum of the numbers.
+ */
+function add($a, $b) {
+    return $a + $b;
+}
+```
+
+<!-- Codacy PatPatBot reviewed: 2024-05-23T15:34:01.575Z -->

docs/description/CakePHP_Commenting_InheritDoc.md

@@ -1 +1,9 @@
-Commenting: Inherit Doc
+Ensures child class members in CakePHP inherit documentation from parent class members. Use the `{@inheritdoc}` tag to seamlessly extend or insert parent documentation into child class comments. Example: 
+
+```php
+/**
+ * {@inheritdoc}
+ */
+```
+
+<!-- Codacy PatPatBot reviewed: 2024-05-23T15:34:10.161Z -->

docs/description/CakePHP_ControlStructures_ControlStructures.md

@@ -1 +1,8 @@
-Control Structures: Control Structures
+Use CakePHP guidelines for control structures to enhance code readability and maintainability. Ensure one space before parentheses, place opening brackets on the same line, and always use curly brackets. Example:
+```
+if (condition) {
+    // action
+}
+```
+
+<!-- Codacy PatPatBot reviewed: 2024-05-23T15:34:15.144Z -->

docs/description/CakePHP_ControlStructures_ElseIfDeclaration.md

@@ -1 +1,20 @@
-Control Structures: Else If Declaration
+Adopts the PSR-12 coding style, enforcing use of `elseif` keyword in control structures for consistency and readability. Avoid using `else if` split into two words. 
+
+**Example:**
+```php
+// Incorrect
+if ($a == $b) {
+    // Code
+} else if ($a > $b) {
+    // Code
+}
+
+// Correct
+if ($a == $b) {
+    // Code
+} elseif ($a > $b) {
+    // Code
+}
+```
+
+<!-- Codacy PatPatBot reviewed: 2024-05-23T15:34:20.775Z -->

docs/description/CakePHP_ControlStructures_WhileStructures.md

@@ -1 +1,10 @@
-Control Structures: While Structures
+Apply consistent spaces and curly brackets to while loops for clarity. Always use one space before the parenthesis and employ curly brackets even for single-line statements.
+
+Example:
+```
+while (condition) {
+    // code block
+}
+```
+
+<!-- Codacy PatPatBot reviewed: 2024-05-23T15:34:24.767Z -->

docs/description/CakePHP_Formatting_BlankLineBeforeReturn.md

@@ -1 +1,23 @@
-Formatting: Blank Line Before Return
+This pattern recommends adding a blank line before a return statement to enhance code readability and maintain consistency. Adding this line helps visually separate the return from other logic, improving the code's clarity.
+```php
+// Before
+function example() {
+  if ($condition) {
+    return $value;
+  }
+  $value += 1;
+  return $value;
+}
+
+// After
+function example() {
+  if ($condition) {
+    return $value;
+  }
+
+  $value += 1;
+  return $value;
+}
+```
+
+<!-- Codacy PatPatBot reviewed: 2024-05-23T15:34:32.064Z -->

docs/description/CakePHP_Functions_ClosureDeclaration.md

@@ -1 +1,11 @@
-Functions: Closure Declaration
+Ensures that closures (anonymous functions) in CakePHP are declared following PSR-12 standards, enhancing readability and consistency. Always include spaces around the use keyword and after the function keyword when declaring closures.
+
+```php
+// Issue: Non-compliant closure declaration
+$closure = function($param){ /* code */ };
+
+// Solution: PSR-12 compliant closure declaration
+$closure = function ($param) use ($dependency) { /* code */ };
+```
+
+<!-- Codacy PatPatBot reviewed: 2024-05-23T15:34:44.285Z -->

docs/description/CakePHP_NamingConventions_ValidFunctionName.md

@@ -1 +1,15 @@
-Naming Conventions: Valid Function Name
+Ensure function names in your code adhere to CakePHP's camelBack conventions. Incorrect naming can cause errors and inconsistencies. For example, replace `send_system_email__to_user` with `sendSystemEmailToUser` to meet the standard.
+
+```php
+// Incorrect:
+function send_system_email__to_user() {
+    // ...
+}
+
+// Correct:
+function sendSystemEmailToUser() {
+    // ...
+}
+```
+
+<!-- Codacy PatPatBot reviewed: 2024-05-23T15:34:49.126Z -->