php-doc

## Documentation (phpDoc)

- **GOLDEN RULE:** Never duplicate signature information without adding value
- For trivial methods where class, method name, and parameter names explain everything
- When documentation would only repeat signature information
- Clearly define purpose/responsibility
- Use active phrasing describing main responsibility
- Avoid unnecessary words
- Be concise and direct

### Class Documentation

#### Writing Style
- Skip phrases like "Class that..." or "Interface for..."
- Don't duplicate method lists or implementation details

### Property Documentation
- Use single-line format for simple `@var` annotations:

```php
/** @var string[] */
private array $name;
```

### Method Documentation

#### Writing Style
- Start with 3rd person singular present tense verb
- Prefer verbs like Returns, Formats, Checks, Creates, Converts, Sets

#### Parameters and Return Values
- Prefer `?Type` over `Type|null` for nullable types
- Only document when adding information beyond PHP types
- Add information about:
  - Array contents (e.g., `@return string[]`)
  - Specific formats or value ranges
  - Important verbal descriptions
- Use two spaces after type: `@return string  primary column sequence name`
- Use two spaces after param: `@param  mixed  $var`
- Skip for self-explanatory parameters (width, height, name)
- Include only when explaining:
  - Additional context
  - Limitations or conditions
  - Unusual usage

### Exception Documentation
- Avoid phrases like "Exception that is thrown when"
- Use natural language and active voice
- Ideally use a single sentence
- Describe the problem, not technical context
- Use consistent phrases across exceptions:
  - "does not exist" for missing items
  - "failed to" for operation failures
  - "cannot" for impossible operations
  - "is not supported" for unsupported features
- Avoid technical jargon, redundant words, implementation details

Examples:
- "The file does not exist."
- "Cannot access the requested class propert