Add missing param comment types based on literals sent to function

[Crabcyborg]

Summary by CodeRabbit

Release Notes

• New Features

  • Introduced automated detection of missing parameter type documentation in PHP functions and methods, with automatic type inference based on analysis of how functions are called and what argument types are passed.

• Documentation

  • Test files updated with enhanced parameter type documentation for improved code clarity and maintainability.

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

[coderabbitai]

📝 Walkthrough

Walkthrough

A new PHP_CodeSniffer sniff is introduced that analyzes function and method definitions to automatically infer and populate missing @param type annotations by examining literal values at call sites. The sniff is registered in the ruleset configuration, and related test file docblocks are updated with missing parameter documentation.

Changes

Cohort / File(s)	Summary
New Sniff Implementation phpcs-sniffs/Formidable/Sniffs/Commenting/AddMissingParamTypeFromCallsSniff.php	Introduces a 516-line sniff that registers on T_FUNCTION tokens, maintains per-file caches, analyzes function/method definitions and docblocks, scans for call sites to infer parameter types from literal values (string, int, float, array, bool, null), and reports fixable errors with automated @param tag additions. Includes helper methods for docblock location, parameter parsing, call site identification, and literal type extraction with nesting depth tracking.
Ruleset Configuration phpcs-sniffs/Formidable/ruleset.xml	Registers the new AddMissingParamTypeFromCalls sniff rule under the Formidable.Commenting section.
Test File Documentation Updates tests/phpunit/emails/test_FrmEmail.php, tests/phpunit/entries/test_FrmShowEntryShortcode.php	Adds missing @param annotations to method docblocks (check_recipients adds $cc_status and $bcc_status; FrmShowEntryShortcode methods add $field_key parameter). No method signatures or runtime behavior modified.

Sequence Diagram

sequenceDiagram
    participant File as PHP File (Input)
    participant Sniff as AddMissingParamTypeFromCalls<br/>Sniff
    participant Cache as Per-File Cache
    participant Parser as Docblock &<br/>Token Parser
    participant Scanner as Call Site<br/>Scanner
    participant Fixer as Docblock<br/>Fixer

    File->>Sniff: Process T_FUNCTION token
    Sniff->>Cache: Check/reset file state
    Sniff->>Parser: Extract function definition<br/>& docblock
    Parser->>Parser: Locate `@param` tags<br/>Identify missing params
    Sniff->>Scanner: Scan file for call sites<br/>of this function
    Scanner->>Scanner: Extract literal argument<br/>types from tokens
    Scanner->>Sniff: Aggregate types per<br/>parameter index
    Sniff->>Sniff: Determine params with<br/>inferred types
    Sniff->>Sniff: Report fixable error<br/>for missing `@param`
    Sniff->>Fixer: Request docblock update
    Fixer->>Fixer: Append `@param` to last<br/>existing `@param` line
    Fixer->>File: Update docblock

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Poem

🐰 A sniff so clever, it hops through your code,
Finding where functions are called down the road,
Peering at parameters, types it divines,
Fixing your docblocks with @param designs! ✨
No more missing docs—automation's grand art!

🚥 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 clearly and concisely summarizes the main change: adding missing @param documentation types by analyzing literal values passed to functions.
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

---

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: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (4)

tests/phpunit/entries/test_FrmShowEntryShortcode.php (4)

826-831: Incorrect @param order in docblock.

The @param annotations should be listed in the same order as the method parameters. The method signature is two_cell_table_row( $field_key, $atts ), but the docblock lists $atts before $field_key.

📝 Proposed fix

 	/**
-	 * `@param` array $atts
 	 * `@param` string $field_key
+	 * `@param` array $atts
 	 *
 	 * `@return` string
 	 */
 	protected function two_cell_table_row( $field_key, $atts ) {

---

867-873: Incorrect @param order in docblock.

Same issue as two_cell_table_row - the @param for $field_key should come before $atts to match the method signature one_cell_table_row( $field_key, $atts ).

📝 Proposed fix

 	/**
-	 * `@param` array $atts
 	 * `@param` string $field_key
+	 * `@param` array $atts
 	 *
 	 * `@return` string
 	 */
 	protected function one_cell_table_row( $field_key, $atts ) {

---

887-893: Incorrect @param order in docblock.

Same issue - the @param for $field_key should come before $atts to match the method signature.

📝 Proposed fix

 	/**
-	 * `@param` array $atts
 	 * `@param` string $field_key
+	 * `@param` array $atts
 	 *
 	 * `@return` string
 	 */
 	protected function label_and_value_plain_text_row( $field_key, $atts ) {

---

910-916: Incorrect @param order in docblock.

Same issue - the @param for $field_key should come before $atts to match the method signature.

📝 Proposed fix

 	/**
-	 * `@param` array $atts
 	 * `@param` string $field_key
+	 * `@param` array $atts
 	 *
 	 * `@return` string
 	 */
 	protected function single_value_plain_text_row( $field_key, $atts ) {

🧹 Nitpick comments (4)

phpcs-sniffs/Formidable/Sniffs/Commenting/AddMissingParamTypeFromCallsSniff.php (4)

106-115: Consider handling interfaces and enums.

The class/method detection only checks for T_CLASS and T_TRAIT. Methods defined in interfaces or enums (PHP 8.1+) won't be recognized as methods, potentially causing incorrect call site matching.

♻️ Suggested improvement

-		$classPtr = $phpcsFile->findPrevious( array( T_CLASS, T_TRAIT ), $stackPtr - 1 );
+		$classPtr = $phpcsFile->findPrevious( array( T_CLASS, T_TRAIT, T_INTERFACE, T_ENUM ), $stackPtr - 1 );

---

288-288: Remove unused parameter $paramCount.

The $paramCount parameter is declared but never used in the method body. Either implement the intended validation logic or remove the parameter.

♻️ Proposed fix

-	private function findCallSiteTypes( File $phpcsFile, $functionName, $isMethod, $className, $paramCount ) {
+	private function findCallSiteTypes( File $phpcsFile, $functionName, $isMethod, $className ) {

Also update the call site at line 118:

-		$callSiteTypes = $this->findCallSiteTypes( $phpcsFile, $functionName, $isMethod, $className, count( $params ) );
+		$callSiteTypes = $this->findCallSiteTypes( $phpcsFile, $functionName, $isMethod, $className );

---

427-427: Remove unused parameter $content.

The $content parameter is declared but never used in the method body.

♻️ Proposed fix

-	private function getLiteralType( $code, $content ) {
+	private function getLiteralType( $code ) {

Also update the call site at line 412:

-		$literalType = $this->getLiteralType( $code, $content );
+		$literalType = $this->getLiteralType( $code );

---

508-514: Hardcoded tab indentation may cause formatting inconsistencies.

The new @param line uses hardcoded tab indentation ("\n\t * @param "). If the codebase uses spaces for indentation, this will produce inconsistent formatting. Consider detecting the existing indentation style from the docblock.