docs: add comprehensive @param and @return annotations #17

New issue

Open

opened 2026-02-20 03:17:25 +00:00 by Clotho · 0 comments

Clotho commented

2026-02-20 03:17:25 +00:00

Member

Documentation Improvement

Files Needing Enhanced Documentation

Priority Files:

src/Api/Controllers/McpApiController.php
- Lines 274, 323: Missing detailed @return documentation
- Complex array structures need better type documentation
src/Api/Middleware/RateLimitApi.php
- Line 82: resolveRateLimitConfig() - Document all possible config keys
- Line 310: getWorkspaceTier() - Missing @return annotation
src/Api/Services/IpRestrictionService.php
- Line 276: parseWhitelistInput() - Add examples of multi-line format
- Document that commas also split entries (not just newlines)

What's Needed

Array Shape Documentation - Use PHPDoc array shapes:

/**
 * @param array{limit: int, window: int, burst?: float} $config
 * @return array{allowed: bool, remaining: int, reset_at: int}
 */

Complex Return Types - Document structure of returned arrays/objects
Examples - Add usage examples for complex methods
Edge Cases - Document behavior for null/empty inputs

Benefits

Better IDE autocomplete
Easier onboarding for new developers
PHPStan/Psalm static analysis improvements
Reduced need to read implementation

Priority

Low - Code works but documentation could be clearer

## Documentation Improvement ### Files Needing Enhanced Documentation **Priority Files**: 1. `src/Api/Controllers/McpApiController.php` - Lines 274, 323: Missing detailed @return documentation - Complex array structures need better type documentation 2. `src/Api/Middleware/RateLimitApi.php` - Line 82: `resolveRateLimitConfig()` - Document all possible config keys - Line 310: `getWorkspaceTier()` - Missing @return annotation 3. `src/Api/Services/IpRestrictionService.php` - Line 276: `parseWhitelistInput()` - Add examples of multi-line format - Document that commas also split entries (not just newlines) ### What's Needed 1. **Array Shape Documentation** - Use PHPDoc array shapes: ```php /** * @param array{limit: int, window: int, burst?: float} $config * @return array{allowed: bool, remaining: int, reset_at: int} */ ``` 2. **Complex Return Types** - Document structure of returned arrays/objects 3. **Examples** - Add usage examples for complex methods 4. **Edge Cases** - Document behavior for null/empty inputs ### Benefits - Better IDE autocomplete - Easier onboarding for new developers - PHPStan/Psalm static analysis improvements - Reduced need to read implementation ### Priority Low - Code works but documentation could be clearer