docs: add PHPDoc to 40+ undocumented public methods #18

New issue

Open

opened 2026-02-20 02:42:10 +00:00 by Clotho · 0 comments

Clotho commented

2026-02-20 02:42:10 +00:00

Member

Issue

40+ public methods across admin modals lack PHPDoc documentation.

Files Missing Documentation

High Priority - Complex Business Logic

src/Website/Hub/View/Modal/Admin/PlatformUser.php (15+ methods):

setTab(string $tab) - Tab switching logic
saveTier() - User tier modification
saveVerification() - User verification status
exportUserData() - GDPR data export
workspaces() - Workspace listing
availablePackages() - Package retrieval
allFeatures() - Feature listing
All provisioning methods (entitlements, packages, features)
render() - View rendering

src/Website/Hub/View/Modal/Admin/Settings.php (10+ methods):

mount() - Complex initialization (lines 80-108)
getUserSetting(string $name, mixed $default = null) - Settings retrieval
updateProfile() - Profile update logic
updatePreferences() - Preferences update (lines 137-162)
updatePassword() - Password change
requestAccountDeletion() - Account deletion (lines 214-230)
All 2FA stub methods (5 methods)

src/Website/Hub/View/Modal/Admin/WaitlistManager.php:

export() - Waitlist data export
getFilteredQuery() - Query builder with filters

src/Website/Hub/View/Modal/Admin/ServiceManager.php:

services() - Service listing
createService() - Service creation
updateService() - Service update
deleteService() - Service deletion
render() - View rendering

Medium Priority - Admin Features

All public methods in:

ActivityLog.php (3+ methods)
Console.php (5+ methods)
Analytics.php (8+ methods)
Databases.php (7+ methods)
Deployments.php (6+ methods)
Honeypot.php (5+ methods)
Platform.php (8+ methods)
Sites.php (6+ methods)

Complex Algorithms Needing Explanation

src/Search/SearchProviderRegistry.php:

fuzzyMatch(string $query, string $target): bool (lines 189-237) - Complex fuzzy matching algorithm
relevanceScore(string $query, SearchResult $result): float (lines 248-304) - Multi-factor scoring
flattenResults(Collection $results): Collection (lines 165-176) - Result flattening

src/Mod/Hub/Controllers/TeapotController.php:

__invoke(Request $request) (lines 23-75) - Honeypot detection and logging
sanitizeHeaders(array $headers): array (lines 50-58) - Header sanitization

src/Mod/Hub/Models/HoneypotHit.php:

getStats(): array (lines 185-205) - Statistics aggregation
All scope methods (3 methods)
Static detection methods (2 methods)

Required PHPDoc Format

/**
 * Short description of what the method does.
 *
 * Optional longer description explaining:
 * - Business logic
 * - Side effects (DB updates, emails, events)
 * - Authorization requirements
 *
 * @param string $param Description of parameter
 * @return void|array|Collection Description of return value
 * @throws ValueError If enum cast fails
 * @throws RuntimeException If external service fails
 */
public function methodName(string $param): void
{
    // Implementation
}

Special Documentation Needs

Component Classes (Form components):

Add @property annotations for public properties
Document authorization props (canGate, canResource, canHide)

Search Algorithms:

Document scoring weights
Explain fuzzy match tolerance
Show example inputs/outputs

Admin Actions:

Document required permissions
List side effects (emails, events, logs)
Explain validation rules

Benefits

Better IDE autocomplete
Clearer API for other developers
Easier code reviews
Self-documenting codebase

Priority

High - Essential for maintainability and onboarding.

Discovered by

Automatic codebase scan (issue #3)

## Issue 40+ public methods across admin modals lack PHPDoc documentation. ## Files Missing Documentation ### High Priority - Complex Business Logic **src/Website/Hub/View/Modal/Admin/PlatformUser.php (15+ methods):** - `setTab(string $tab)` - Tab switching logic - `saveTier()` - User tier modification - `saveVerification()` - User verification status - `exportUserData()` - GDPR data export - `workspaces()` - Workspace listing - `availablePackages()` - Package retrieval - `allFeatures()` - Feature listing - All provisioning methods (entitlements, packages, features) - `render()` - View rendering **src/Website/Hub/View/Modal/Admin/Settings.php (10+ methods):** - `mount()` - Complex initialization (lines 80-108) - `getUserSetting(string $name, mixed $default = null)` - Settings retrieval - `updateProfile()` - Profile update logic - `updatePreferences()` - Preferences update (lines 137-162) - `updatePassword()` - Password change - `requestAccountDeletion()` - Account deletion (lines 214-230) - All 2FA stub methods (5 methods) **src/Website/Hub/View/Modal/Admin/WaitlistManager.php:** - `export()` - Waitlist data export - `getFilteredQuery()` - Query builder with filters **src/Website/Hub/View/Modal/Admin/ServiceManager.php:** - `services()` - Service listing - `createService()` - Service creation - `updateService()` - Service update - `deleteService()` - Service deletion - `render()` - View rendering ### Medium Priority - Admin Features All public methods in: - `ActivityLog.php` (3+ methods) - `Console.php` (5+ methods) - `Analytics.php` (8+ methods) - `Databases.php` (7+ methods) - `Deployments.php` (6+ methods) - `Honeypot.php` (5+ methods) - `Platform.php` (8+ methods) - `Sites.php` (6+ methods) ### Complex Algorithms Needing Explanation **src/Search/SearchProviderRegistry.php:** - `fuzzyMatch(string $query, string $target): bool` (lines 189-237) - Complex fuzzy matching algorithm - `relevanceScore(string $query, SearchResult $result): float` (lines 248-304) - Multi-factor scoring - `flattenResults(Collection $results): Collection` (lines 165-176) - Result flattening **src/Mod/Hub/Controllers/TeapotController.php:** - `__invoke(Request $request)` (lines 23-75) - Honeypot detection and logging - `sanitizeHeaders(array $headers): array` (lines 50-58) - Header sanitization **src/Mod/Hub/Models/HoneypotHit.php:** - `getStats(): array` (lines 185-205) - Statistics aggregation - All scope methods (3 methods) - Static detection methods (2 methods) ## Required PHPDoc Format ```php /** * Short description of what the method does. * * Optional longer description explaining: * - Business logic * - Side effects (DB updates, emails, events) * - Authorization requirements * * @param string $param Description of parameter * @return void|array|Collection Description of return value * @throws ValueError If enum cast fails * @throws RuntimeException If external service fails */ public function methodName(string $param): void { // Implementation } ``` ## Special Documentation Needs **Component Classes** (Form components): - Add `@property` annotations for public properties - Document authorization props (`canGate`, `canResource`, `canHide`) **Search Algorithms:** - Document scoring weights - Explain fuzzy match tolerance - Show example inputs/outputs **Admin Actions:** - Document required permissions - List side effects (emails, events, logs) - Explain validation rules ## Benefits - Better IDE autocomplete - Clearer API for other developers - Easier code reviews - Self-documenting codebase ## Priority **High** - Essential for maintainability and onboarding. ## Discovered by Automatic codebase scan (issue #3)