New sniff to make replace var name in return with a readable text ver…

[Crabcyborg]

…sion

Summary by CodeRabbit

• Documentation

  • Refined PHPDoc return descriptions across many components for clearer, consistent return-value wording.

• Chores

  • Added a new code-quality rule to detect and auto-fix variable-named @return tags into human-readable return descriptions, improving docblock consistency.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Standardizes PHPDoc @return annotations by replacing variable-named descriptions with human-readable descriptions and adds a PHP_CodeSniffer sniff plus ruleset entry to detect and auto-fix these patterns. No runtime behavior or public API signatures were changed.

Changes

Cohort / File(s)	Summary
PHPDoc return updates classes/controllers/FrmXMLController.php, classes/helpers/FrmAppHelper.php, classes/helpers/FrmEntriesHelper.php, classes/helpers/FrmEntriesListHelper.php, classes/helpers/FrmFieldsHelper.php, classes/models/FrmAddon.php, classes/models/FrmEmail.php, classes/models/FrmEntry.php, classes/models/FrmFieldFormHtml.php, classes/models/FrmFormAction.php, classes/models/FrmValidate.php, classes/models/fields/FrmFieldCaptcha.php, classes/models/fields/FrmFieldType.php, stripe/helpers/FrmStrpLiteSubscriptionHelper.php, tests/phpunit/stripe/FrmStrpLiteUnitTest.php	Rewrote @return docblocks from variable-named format (e.g., @return string $value) to human-readable descriptions (e.g., @return string Value.). No code, signature, or behavior changes.
New PHPCS sniff phpcs-sniffs/Formidable/Sniffs/Commenting/ConvertReturnVariableToDescriptionSniff.php	Adds a new sniff that detects @return type $variable patterns, generates a readable description from the variable name (handles leading/underscores, underscores, and common abbreviations), reports a fixable error, and applies an auto-fix. Implements register(), process(), and variableToDescription().
Ruleset registration phpcs-sniffs/Formidable/ruleset.xml	Adds <rule ref="Formidable.Commenting.ConvertReturnVariableToDescription" /> to enable the new sniff in the Formidable ruleset.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Organize sniffs #2799 — Modifies PHPCS configuration/sniffs; closely related to adding or reorganizing sniffs and rules.
• Move formidable sniffs to separate ruleset file #2801 — Alters Formidable PHPCS sniffs/ruleset; directly related to ruleset and custom-sniff changes.
• Add var comments to object properties #2611 — Prior docblock edits overlapping FrmAddon.php changes and other PHPDoc standardization efforts.

Poem

🐰✍️ I hop through docblocks, tidy and spry,
From $entry_id to "Entry ID." I fly,
A sniff in my paws, I fix with delight,
Clear returns by day, and neat docs by night —
Hooray for tidy code, nibble and bite! 🥕

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding a new PHP_CodeSniffer sniff to replace variable names in @return docblock tags with readable descriptions.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

🧹 Recent nitpick comments

phpcs-sniffs/Formidable/Sniffs/Commenting/ConvertReturnVariableToDescriptionSniff.php (1)

103-140: Consider handling camelCase variable names and edge case validation.

The implementation handles snake_case variables well, but note these limitations:

1. camelCase variables are not split: $entryId → "Entryid." instead of "Entry ID."
2. Edge case: Variable names like $_ would produce an empty description, resulting in @return type with trailing space.

If the codebase follows a strict snake_case convention, this may be acceptable. Otherwise, consider adding camelCase support:

🔧 Optional: Add camelCase support

 private function variableToDescription( $variableName ) {
     // Remove the $ prefix and any leading underscores.
     $name = ltrim( $variableName, '$_' );

+    // Convert camelCase to snake_case for uniform processing.
+    $name = preg_replace( '/([a-z])([A-Z])/', '$1_$2', $name );
+
     // Split by underscores.
     $parts = explode( '_', $name );

🔧 Optional: Guard against empty description

     // Join words and add period.
     $description = implode( ' ', $words );

+    // Fallback if description is empty (e.g., variable was just $_).
+    if ( empty( $description ) ) {
+        return 'Result.';
+    }
+
     if ( ! empty( $description ) ) {
         $description .= '.';
     }

     return $description;
 }

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 97bf7a3 and 5af7260.

📒 Files selected for processing (3)

• classes/controllers/FrmXMLController.php
• classes/helpers/FrmEntriesHelper.php
• phpcs-sniffs/Formidable/Sniffs/Commenting/ConvertReturnVariableToDescriptionSniff.php

🚧 Files skipped from review as they are similar to previous changes (1)

• classes/controllers/FrmXMLController.php

🧰 Additional context used

📓 Path-based instructions (1)

**/*.php

⚙️ CodeRabbit configuration file

**/*.php: - Do not make suggestions when we use x.x for a version placeholder. This is used like "@SInCE x.x" in a PHP doc comment, but also like 'x.x' when functions like _deprecated_function() are used.

• Treat these placeholders as acceptable in this codebase.

Files:

• phpcs-sniffs/Formidable/Sniffs/Commenting/ConvertReturnVariableToDescriptionSniff.php
• classes/helpers/FrmEntriesHelper.php

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: PHP 8 tests in WP 6.9
• GitHub Check: Cypress
• GitHub Check: PHP 7.4 tests in WP 6.9

🔇 Additional comments (4)

classes/helpers/FrmEntriesHelper.php (2)

122-122: LGTM!

The updated return annotation is more descriptive and follows PHPDoc best practices by describing the returned value rather than echoing the variable name.

---

146-146: LGTM!

The updated return annotation clearly documents when the boolean is true, which is more informative than the previous variable-name-based description. This follows standard PHPDoc conventions for boolean returns.

phpcs-sniffs/Formidable/Sniffs/Commenting/ConvertReturnVariableToDescriptionSniff.php (2)

29-38: LGTM!

The register() method correctly returns T_DOC_COMMENT_TAG to listen for doc comment tags.

---

48-88: LGTM!

The process() method correctly:

• Filters for @return tags only
• Uses a precise regex to match type $variable_name patterns while excluding descriptions that already contain text
• Properly handles union types and namespaced types in the regex
• Applies the fix correctly using the fixer API

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@classes/controllers/FrmXMLController.php`:
- Line 763: Update the docblock in FrmXMLController where the return description
currently reads "Csv fields." to use the correct uppercase abbreviation "CSV
fields."; locate the docblock associated with the relevant method in the
FrmXMLController class (the return tag on the method around the comment) and
replace "Csv" with "CSV" so the abbreviation conforms to the project's
sniff/uppercase rules.

🧹 Nitpick comments (1)

phpcs-sniffs/Formidable/Sniffs/Commenting/ConvertReturnVariableToDescriptionSniff.php (1)

102-139: Consider handling camelCase variable names.

The current implementation only splits on underscores, which means camelCase variables like $entryId would produce Entryid. instead of the more readable Entry ID.. If the codebase consistently uses snake_case, this is fine. Otherwise, consider adding camelCase splitting.

Optional enhancement for camelCase support

 private function variableToDescription( $variableName ) {
     // Remove the $ prefix and any leading underscores.
     $name = ltrim( $variableName, '$_' );

+    // Convert camelCase to snake_case first.
+    $name = preg_replace( '/([a-z])([A-Z])/', '$1_$2', $name );
+
     // Split by underscores.
     $parts = explode( '_', $name );

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e344678 and d1d3ae1.

📒 Files selected for processing (17)

• classes/controllers/FrmXMLController.php
• classes/helpers/FrmAppHelper.php
• classes/helpers/FrmEntriesHelper.php
• classes/helpers/FrmEntriesListHelper.php
• classes/helpers/FrmFieldsHelper.php
• classes/models/FrmAddon.php
• classes/models/FrmEmail.php
• classes/models/FrmEntry.php
• classes/models/FrmFieldFormHtml.php
• classes/models/FrmFormAction.php
• classes/models/FrmValidate.php
• classes/models/fields/FrmFieldCaptcha.php
• classes/models/fields/FrmFieldType.php
• phpcs-sniffs/Formidable/Sniffs/Commenting/ConvertReturnVariableToDescriptionSniff.php
• phpcs-sniffs/Formidable/ruleset.xml
• stripe/helpers/FrmStrpLiteSubscriptionHelper.php
• tests/phpunit/stripe/FrmStrpLiteUnitTest.php

🧰 Additional context used

📓 Path-based instructions (1)

**/*.php

⚙️ CodeRabbit configuration file

**/*.php: - Do not make suggestions when we use x.x for a version placeholder. This is used like "@SInCE x.x" in a PHP doc comment, but also like 'x.x' when functions like _deprecated_function() are used.

• Treat these placeholders as acceptable in this codebase.

Files:

• classes/models/FrmValidate.php
• classes/models/fields/FrmFieldCaptcha.php
• tests/phpunit/stripe/FrmStrpLiteUnitTest.php
• classes/models/FrmEmail.php
• classes/helpers/FrmEntriesListHelper.php
• classes/helpers/FrmFieldsHelper.php
• classes/models/FrmAddon.php
• classes/models/FrmEntry.php
• classes/helpers/FrmAppHelper.php
• classes/controllers/FrmXMLController.php
• classes/models/fields/FrmFieldType.php
• classes/models/FrmFieldFormHtml.php
• classes/helpers/FrmEntriesHelper.php
• phpcs-sniffs/Formidable/Sniffs/Commenting/ConvertReturnVariableToDescriptionSniff.php
• stripe/helpers/FrmStrpLiteSubscriptionHelper.php
• classes/models/FrmFormAction.php

🔇 Additional comments (21)

classes/models/fields/FrmFieldType.php (1)

1840-1840: LGTM! Documentation improvement.

The PHPDoc return annotation has been updated to use a more readable description ("New value.") instead of a variable-like token ("$new_value"). This is a documentation-only change with no impact on functionality.

classes/models/FrmFieldFormHtml.php (1)

524-524: LGTM! Documentation improvement.

The PHPDoc return annotation has been updated to use a more readable description ("Classes.") instead of a variable-like token ("$classes"). This is a documentation-only change with no impact on functionality.

classes/models/FrmFormAction.php (1)

367-367: LGTM! Documentation improvement.

The PHPDoc return annotation has been updated to use a more readable description ("Post ID.") instead of a variable-like token ("$post_id"). This is a documentation-only change with no impact on functionality.

classes/helpers/FrmEntriesListHelper.php (1)

295-295: LGTM! Documentation improvement.

The PHPDoc return annotation has been updated to use a more readable description ("Primary column.") instead of a variable-like token ("$primary_column"). This is a documentation-only change with no impact on functionality.

classes/models/FrmEmail.php (1)

661-661: LGTM! Documentation improvement.

The PHPDoc return annotation has been updated to use a more readable description ("Emails.") instead of a variable-like token ("$emails"). This is a documentation-only change with no impact on functionality.

tests/phpunit/stripe/FrmStrpLiteUnitTest.php (1)

195-197: LGTM!

The return annotation update from $customer_id to Customer ID. follows the new documentation convention being introduced by this PR's sniff.

classes/models/FrmAddon.php (1)

173-183: LGTM!

The return annotation update from $_data to Data. correctly applies the new documentation convention, properly handling the leading underscore in the original variable name.

classes/helpers/FrmAppHelper.php (3)

273-275: LGTM!

The return annotation update to Frm settings. follows the new documentation convention.

---

870-872: LGTM!

The return annotation update to Value. follows the new documentation convention.

---

3219-3221: LGTM!

The return annotation update to Time ago. provides a clear, readable description of the return value.

stripe/helpers/FrmStrpLiteSubscriptionHelper.php (1)

38-41: LGTM!

The return annotation update from $sub_id to Sub ID. correctly applies the new documentation convention, properly uppercasing the "ID" abbreviation.

classes/helpers/FrmEntriesHelper.php (2)

119-123: LGTM!

The return annotation update to New value. follows the new documentation convention.

---

143-147: LGTM!

The return annotation update to Value is posted. provides a clear, readable description following the new documentation convention.

classes/models/FrmValidate.php (1)

32-34: LGTM!

The PHPDoc return annotation correctly follows the new convention of using a descriptive text instead of variable name.

classes/models/fields/FrmFieldCaptcha.php (1)

431-433: LGTM!

The PHPDoc return annotation correctly follows the new convention.

classes/models/FrmEntry.php (1)

20-20: LGTM!

All PHPDoc return annotations have been correctly updated to use descriptive text. The abbreviations like id are properly converted to uppercase ID, consistent with the new sniff's logic.

Also applies to: 32-32, 321-321, 336-336, 777-777, 797-797, 845-845, 999-999, 1135-1135, 1162-1162, 1235-1235, 1250-1250

phpcs-sniffs/Formidable/Sniffs/Commenting/ConvertReturnVariableToDescriptionSniff.php (2)

28-37: LGTM!

The sniff class structure and registration are correctly implemented following PHP_CodeSniffer conventions.

---

47-87: LGTM!

The process method correctly:

• Filters for @return tags only
• Uses a well-crafted regex to match type $variable patterns
• Supports union types (bool|int) and namespaced types
• Provides fixable errors with clear messaging

phpcs-sniffs/Formidable/ruleset.xml (1)

39-42: LGTM!

The new sniff rule is correctly added under the Commenting section, following the established naming convention and structure.

classes/helpers/FrmFieldsHelper.php (2)

1615-1619: LGTM!

PHPDoc return annotation correctly updated from variable name format to descriptive text format, aligning with the new sniff's standardization effort.

---

1753-1757: LGTM!

PHPDoc return annotation correctly updated to use descriptive text instead of variable name format.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}