@mytechtoday/augment-extensions 0.7.0 → 1.2.0

package/augment-extensions/coding-standards/php/rules/documentation.md

@@ -1,425 +1,425 @@
-# Documentation Standards
-
-## Overview
-
-Proper documentation improves code maintainability and helps developers understand code intent. This document defines PHPDoc standards and documentation best practices.
-
----
-
-## PHPDoc Blocks
-
-### Function and Method Documentation
-
-**Rules:**
-- All public methods MUST have PHPDoc blocks
-- Include description, parameters, return type, and exceptions
-- Use proper PHPDoc tags
-
-**Required Tags:**
-- `@param` - Document all parameters with types and descriptions
-- `@return` - Document return type and description
-- `@throws` - Document all thrown exceptions
-
-**Examples:**
-```php
-// ✅ Good - Complete documentation
-/**
- * Retrieves a user by their unique identifier.
- *
- * @param int $id The user's unique identifier
- * @return User|null The user object if found, null otherwise
- * @throws DatabaseException If database connection fails
- * @throws InvalidArgumentException If ID is negative
- */
-public function getUserById(int $id): ?User
-{
-    if ($id < 0) {
-        throw new InvalidArgumentException('User ID must be positive');
-    }
-    
-    return $this->repository->find($id);
-}
-
-// ✅ Good - With examples for complex functions
-/**
- * Calculates the total price including tax and discounts.
- *
- * Example:
- * ```php
- * $calculator = new PriceCalculator();
- * $total = $calculator->calculate(100.00, 0.2, 10.00);
- * // Returns: 110.00 (100 + 20% tax - 10 discount)
- * ```
- *
- * @param float $basePrice The base price before tax and discounts
- * @param float $taxRate The tax rate as a decimal (e.g., 0.2 for 20%)
- * @param float $discount The discount amount to subtract
- * @return float The final calculated price
- */
-public function calculate(float $basePrice, float $taxRate, float $discount): float
-{
-    return ($basePrice * (1 + $taxRate)) - $discount;
-}
-
-// ❌ Bad - Missing documentation
-public function getUserById(int $id): ?User
-{
-    return $this->repository->find($id);
-}
-
-// ❌ Bad - Incomplete documentation
-/**
- * Gets user
- */
-public function getUserById(int $id): ?User
-{
-    return $this->repository->find($id);
-}
-```
-
-### Class Documentation
-
-**Rules:**
-- All classes MUST have PHPDoc blocks
-- Describe the class purpose and responsibility
-- Include package/namespace information when relevant
-
-**Optional Tags:**
-- `@package` - Indicate namespace/package
-- `@author` - Author information (optional)
-- `@property` - Document magic properties
-- `@method` - Document magic methods
-
-**Examples:**
-```php
-// ✅ Good - Class documentation
-/**
- * Manages user authentication and authorization.
- *
- * This service handles user login, logout, password verification,
- * and permission checking. It integrates with the session manager
- * and user repository.
- *
- * @package App\Services\Auth
- */
-class AuthenticationService
-{
-    // ...
-}
-
-// ✅ Good - With magic properties
-/**
- * Represents a user in the system.
- *
- * @property-read int $id The user's unique identifier
- * @property string $name The user's full name
- * @property string $email The user's email address
- */
-class User
-{
-    // ...
-}
-
-// ✅ Good - With magic methods
-/**
- * Base repository with dynamic query methods.
- *
- * @method User|null findByEmail(string $email)
- * @method User[] findByStatus(string $status)
- */
-class UserRepository
-{
-    public function __call(string $method, array $args)
-    {
-        // Magic method implementation
-    }
-}
-```
-
-### Property Documentation
-
-**Rules:**
-- Document complex or non-obvious properties
-- Use `@var` tag for type information
-- Include description when type alone isn't clear
-
-**Examples:**
-```php
-// ✅ Good - Property documentation
-class OrderProcessor
-{
-    /**
-     * Maximum number of retry attempts for failed orders.
-     *
-     * @var int
-     */
-    private const MAX_RETRIES = 3;
-    
-    /**
-     * The payment gateway instance for processing payments.
-     *
-     * @var PaymentGatewayInterface
-     */
-    private PaymentGatewayInterface $gateway;
-    
-    /**
-     * Cache of processed order IDs to prevent duplicate processing.
-     *
-     * @var array<int, bool>
-     */
-    private array $processedOrders = [];
-}
-```
-
----
-
-## Type Annotations
-
-### Array Type Annotations
-
-**Rules:**
-- Use array shape notation for structured arrays
-- Use generic array notation for simple arrays
-- Be specific about array contents
-
-**Examples:**
-```php
-// ✅ Good - Array shape notation
-/**
- * @param array{id: int, name: string, email: string} $userData
- * @return array{success: bool, message: string}
- */
-public function processUser(array $userData): array
-{
-    // ...
-}
-
-// ✅ Good - Generic array notation
-/**
- * @param array<int, string> $items Array of strings indexed by integers
- * @return array<string, mixed> Associative array with string keys
- */
-public function processItems(array $items): array
-{
-    // ...
-}
-
-// ✅ Good - Array of objects
-/**
- * @param User[] $users Array of User objects
- * @return int[] Array of user IDs
- */
-public function extractUserIds(array $users): array
-{
-    return array_map(fn($user) => $user->id, $users);
-}
-```
-
-### Nullable and Union Types
-
-**Rules:**
-- Document nullable types clearly
-- Use union type notation for multiple possible types
-
-**Examples:**
-```php
-// ✅ Good - Nullable type
-/**
- * @param int|null $userId The user ID, or null for guest users
- * @return User|null The user object, or null if not found
- */
-public function findUser(?int $userId): ?User
-{
-    // ...
-}
-
-// ✅ Good - Union types
-/**
- * @param int|string $identifier User ID or email address
- * @return User|false The user object, or false if not found
- */
-public function findByIdentifier(int|string $identifier): User|false
-{
-    // ...
-}
-```
-
----
-
-## Inline Comments
-
-### When to Use Inline Comments
-
-**Rules:**
-- Explain WHY, not WHAT
-- Comment complex algorithms or business logic
-- Avoid obvious comments
-- Keep comments up-to-date with code
-
-**Examples:**
-```php
-// ✅ Good - Explains WHY
-// We need to clear the cache here because the user's permissions
-// may have changed, affecting their access to cached resources
-Cache::flush();
-
-// ✅ Good - Explains complex logic
-// Calculate discount using tiered pricing:
-// 0-10 items: no discount
-// 11-50 items: 10% discount
-// 51+ items: 20% discount
-$discount = match (true) {
-    $quantity <= 10 => 0,
-    $quantity <= 50 => 0.10,
-    default => 0.20,
-};
-
-// ❌ Bad - Obvious comment
-// Increment counter
-$counter++;
-
-// ❌ Bad - Outdated comment
-// Set status to pending
-$order->status = 'completed';  // Comment doesn't match code!
-```
-
-### TODO Comments
-
-**Rules:**
-- Use TODO comments for future improvements
-- Include ticket/issue number when available
-- Include date and author
-
-**Examples:**
-```php
-// ✅ Good - TODO with context
-// TODO(john, 2024-01-15): Refactor to use new payment gateway API
-// See ticket #1234
-public function processPayment(Order $order): bool
-{
-    // Legacy implementation
-}
-
-// ❌ Bad - Vague TODO
-// TODO: fix this
-public function processPayment(Order $order): bool
-{
-    // ...
-}
-```
-
----
-
-## README and Documentation Files
-
-### README.md Structure
-
-**Sections:**
-1. Project title and description
-2. Installation instructions
-3. Configuration
-4. Usage examples
-5. API documentation (if applicable)
-6. Contributing guidelines
-7. License
-
-**Example:**
-```markdown
-# User Management Service
-
-A comprehensive user management service for handling authentication,
-authorization, and user profile management.
-
-## Installation
-
-```bash
-composer require myapp/user-service
-```
-
-## Configuration
-
-```php
-// config/user-service.php
-return [
-    'session_timeout' => 3600,
-    'password_min_length' => 8,
-];
-```
-
-## Usage
-
-```php
-use App\Services\UserService;
-
-$service = new UserService();
-$user = $service->createUser([
-    'name' => 'John Doe',
-    'email' => 'john@example.com',
-]);
-```
-```
-
----
-
-## API Documentation
-
-### Generate API Documentation
-
-**Tools:**
-- phpDocumentor
-- ApiGen
-- Sami
-
-**Example:**
-```bash
-# Generate API documentation
-phpdoc -d src/ -t docs/api/
-```
-
----
-
-## Best Practices
-
-### Keep Documentation Current
-
-**Rules:**
-- Update documentation when code changes
-- Review documentation during code reviews
-- Remove outdated comments
-
-### Be Concise
-
-**Rules:**
-- Use clear, concise language
-- Avoid redundant information
-- Focus on important details
-
-### Use Examples
-
-**Rules:**
-- Provide code examples for complex functionality
-- Show common use cases
-- Include expected output when relevant
-
-**Examples:**
-```php
-/**
- * Formats a date according to the specified format.
- *
- * Example:
- * ```php
- * $formatter = new DateFormatter();
- * echo $formatter->format(new DateTime(), 'Y-m-d');
- * // Output: 2024-01-15
- * ```
- *
- * @param DateTime $date The date to format
- * @param string $format The desired format (PHP date format)
- * @return string The formatted date string
- */
-public function format(DateTime $date, string $format): string
-{
-    return $date->format($format);
-}
-```
-
+# Documentation Standards
+
+## Overview
+
+Proper documentation improves code maintainability and helps developers understand code intent. This document defines PHPDoc standards and documentation best practices.
+
+---
+
+## PHPDoc Blocks
+
+### Function and Method Documentation
+
+**Rules:**
+- All public methods MUST have PHPDoc blocks
+- Include description, parameters, return type, and exceptions
+- Use proper PHPDoc tags
+
+**Required Tags:**
+- `@param` - Document all parameters with types and descriptions
+- `@return` - Document return type and description
+- `@throws` - Document all thrown exceptions
+
+**Examples:**
+```php
+// ✅ Good - Complete documentation
+/**
+ * Retrieves a user by their unique identifier.
+ *
+ * @param int $id The user's unique identifier
+ * @return User|null The user object if found, null otherwise
+ * @throws DatabaseException If database connection fails
+ * @throws InvalidArgumentException If ID is negative
+ */
+public function getUserById(int $id): ?User
+{
+    if ($id < 0) {
+        throw new InvalidArgumentException('User ID must be positive');
+    }
+    
+    return $this->repository->find($id);
+}
+
+// ✅ Good - With examples for complex functions
+/**
+ * Calculates the total price including tax and discounts.
+ *
+ * Example:
+ * ```php
+ * $calculator = new PriceCalculator();
+ * $total = $calculator->calculate(100.00, 0.2, 10.00);
+ * // Returns: 110.00 (100 + 20% tax - 10 discount)
+ * ```
+ *
+ * @param float $basePrice The base price before tax and discounts
+ * @param float $taxRate The tax rate as a decimal (e.g., 0.2 for 20%)
+ * @param float $discount The discount amount to subtract
+ * @return float The final calculated price
+ */
+public function calculate(float $basePrice, float $taxRate, float $discount): float
+{
+    return ($basePrice * (1 + $taxRate)) - $discount;
+}
+
+// ❌ Bad - Missing documentation
+public function getUserById(int $id): ?User
+{
+    return $this->repository->find($id);
+}
+
+// ❌ Bad - Incomplete documentation
+/**
+ * Gets user
+ */
+public function getUserById(int $id): ?User
+{
+    return $this->repository->find($id);
+}
+```
+
+### Class Documentation
+
+**Rules:**
+- All classes MUST have PHPDoc blocks
+- Describe the class purpose and responsibility
+- Include package/namespace information when relevant
+
+**Optional Tags:**
+- `@package` - Indicate namespace/package
+- `@author` - Author information (optional)
+- `@property` - Document magic properties
+- `@method` - Document magic methods
+
+**Examples:**
+```php
+// ✅ Good - Class documentation
+/**
+ * Manages user authentication and authorization.
+ *
+ * This service handles user login, logout, password verification,
+ * and permission checking. It integrates with the session manager
+ * and user repository.
+ *
+ * @package App\Services\Auth
+ */
+class AuthenticationService
+{
+    // ...
+}
+
+// ✅ Good - With magic properties
+/**
+ * Represents a user in the system.
+ *
+ * @property-read int $id The user's unique identifier
+ * @property string $name The user's full name
+ * @property string $email The user's email address
+ */
+class User
+{
+    // ...
+}
+
+// ✅ Good - With magic methods
+/**
+ * Base repository with dynamic query methods.
+ *
+ * @method User|null findByEmail(string $email)
+ * @method User[] findByStatus(string $status)
+ */
+class UserRepository
+{
+    public function __call(string $method, array $args)
+    {
+        // Magic method implementation
+    }
+}
+```
+
+### Property Documentation
+
+**Rules:**
+- Document complex or non-obvious properties
+- Use `@var` tag for type information
+- Include description when type alone isn't clear
+
+**Examples:**
+```php
+// ✅ Good - Property documentation
+class OrderProcessor
+{
+    /**
+     * Maximum number of retry attempts for failed orders.
+     *
+     * @var int
+     */
+    private const MAX_RETRIES = 3;
+    
+    /**
+     * The payment gateway instance for processing payments.
+     *
+     * @var PaymentGatewayInterface
+     */
+    private PaymentGatewayInterface $gateway;
+    
+    /**
+     * Cache of processed order IDs to prevent duplicate processing.
+     *
+     * @var array<int, bool>
+     */
+    private array $processedOrders = [];
+}
+```
+
+---
+
+## Type Annotations
+
+### Array Type Annotations
+
+**Rules:**
+- Use array shape notation for structured arrays
+- Use generic array notation for simple arrays
+- Be specific about array contents
+
+**Examples:**
+```php
+// ✅ Good - Array shape notation
+/**
+ * @param array{id: int, name: string, email: string} $userData
+ * @return array{success: bool, message: string}
+ */
+public function processUser(array $userData): array
+{
+    // ...
+}
+
+// ✅ Good - Generic array notation
+/**
+ * @param array<int, string> $items Array of strings indexed by integers
+ * @return array<string, mixed> Associative array with string keys
+ */
+public function processItems(array $items): array
+{
+    // ...
+}
+
+// ✅ Good - Array of objects
+/**
+ * @param User[] $users Array of User objects
+ * @return int[] Array of user IDs
+ */
+public function extractUserIds(array $users): array
+{
+    return array_map(fn($user) => $user->id, $users);
+}
+```
+
+### Nullable and Union Types
+
+**Rules:**
+- Document nullable types clearly
+- Use union type notation for multiple possible types
+
+**Examples:**
+```php
+// ✅ Good - Nullable type
+/**
+ * @param int|null $userId The user ID, or null for guest users
+ * @return User|null The user object, or null if not found
+ */
+public function findUser(?int $userId): ?User
+{
+    // ...
+}
+
+// ✅ Good - Union types
+/**
+ * @param int|string $identifier User ID or email address
+ * @return User|false The user object, or false if not found
+ */
+public function findByIdentifier(int|string $identifier): User|false
+{
+    // ...
+}
+```
+
+---
+
+## Inline Comments
+
+### When to Use Inline Comments
+
+**Rules:**
+- Explain WHY, not WHAT
+- Comment complex algorithms or business logic
+- Avoid obvious comments
+- Keep comments up-to-date with code
+
+**Examples:**
+```php
+// ✅ Good - Explains WHY
+// We need to clear the cache here because the user's permissions
+// may have changed, affecting their access to cached resources
+Cache::flush();
+
+// ✅ Good - Explains complex logic
+// Calculate discount using tiered pricing:
+// 0-10 items: no discount
+// 11-50 items: 10% discount
+// 51+ items: 20% discount
+$discount = match (true) {
+    $quantity <= 10 => 0,
+    $quantity <= 50 => 0.10,
+    default => 0.20,
+};
+
+// ❌ Bad - Obvious comment
+// Increment counter
+$counter++;
+
+// ❌ Bad - Outdated comment
+// Set status to pending
+$order->status = 'completed';  // Comment doesn't match code!
+```
+
+### TODO Comments
+
+**Rules:**
+- Use TODO comments for future improvements
+- Include ticket/issue number when available
+- Include date and author
+
+**Examples:**
+```php
+// ✅ Good - TODO with context
+// TODO(john, 2024-01-15): Refactor to use new payment gateway API
+// See ticket #1234
+public function processPayment(Order $order): bool
+{
+    // Legacy implementation
+}
+
+// ❌ Bad - Vague TODO
+// TODO: fix this
+public function processPayment(Order $order): bool
+{
+    // ...
+}
+```
+
+---
+
+## README and Documentation Files
+
+### README.md Structure
+
+**Sections:**
+1. Project title and description
+2. Installation instructions
+3. Configuration
+4. Usage examples
+5. API documentation (if applicable)
+6. Contributing guidelines
+7. License
+
+**Example:**
+```markdown
+# User Management Service
+
+A comprehensive user management service for handling authentication,
+authorization, and user profile management.
+
+## Installation
+
+```bash
+composer require myapp/user-service
+```
+
+## Configuration
+
+```php
+// config/user-service.php
+return [
+    'session_timeout' => 3600,
+    'password_min_length' => 8,
+];
+```
+
+## Usage
+
+```php
+use App\Services\UserService;
+
+$service = new UserService();
+$user = $service->createUser([
+    'name' => 'John Doe',
+    'email' => 'john@example.com',
+]);
+```
+```
+
+---
+
+## API Documentation
+
+### Generate API Documentation
+
+**Tools:**
+- phpDocumentor
+- ApiGen
+- Sami
+
+**Example:**
+```bash
+# Generate API documentation
+phpdoc -d src/ -t docs/api/
+```
+
+---
+
+## Best Practices
+
+### Keep Documentation Current
+
+**Rules:**
+- Update documentation when code changes
+- Review documentation during code reviews
+- Remove outdated comments
+
+### Be Concise
+
+**Rules:**
+- Use clear, concise language
+- Avoid redundant information
+- Focus on important details
+
+### Use Examples
+
+**Rules:**
+- Provide code examples for complex functionality
+- Show common use cases
+- Include expected output when relevant
+
+**Examples:**
+```php
+/**
+ * Formats a date according to the specified format.
+ *
+ * Example:
+ * ```php
+ * $formatter = new DateFormatter();
+ * echo $formatter->format(new DateTime(), 'Y-m-d');
+ * // Output: 2024-01-15
+ * ```
+ *
+ * @param DateTime $date The date to format
+ * @param string $format The desired format (PHP date format)
+ * @return string The formatted date string
+ */
+public function format(DateTime $date, string $format): string
+{
+    return $date->format($format);
+}
+```
+