> ## Documentation Index
> Fetch the complete documentation index at: https://geni.masiting.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Scramble-Compatible PHPDoc

> Document endpoints using standard PHPDoc docblock annotations.

## Overview

For developers who prefer docblocks over PHP 8 attributes, Geni provides comprehensive support for standard PHPDoc annotations.

Geni is fully compatible with [Scramble](https://scramble.dedoc.co/) docblock conventions:

```php theme={null}
/**
 * List published articles.
 *
 * Retrieve a paginated list of published articles with author relationships.
 *
 * @tags Articles, Content
 * @operationId articles.index
 *
 * @queryParam page int The page number to fetch. Example: 1
 * @queryParam per_page int Number of items per page. Example: 15
 * @queryParam sort string Sort field and direction (-created_at).
 *
 * @response 200 AnonymousResourceCollection<ArticleResource>
 * @response 401 {"message": "Unauthenticated."}
 *
 * @unauthenticated
 */
public function index()
{
    // ...
}
```

## Supported Tags

### Operation Metadata

* **Summary & Description**: The first line of the docblock is treated as the summary. Subsequent lines before tags are treated as the long description.
* `@tags TagName, AnotherTag`: Assigns operations to OpenAPI tags.
* `@operationId customOperationId`: Explicitly assigns an `operationId`.
* `@deprecated`: Marks the operation as deprecated.
* `@unauthenticated`: Omits security requirements for this specific endpoint.

### Parameters

* `@queryParam name type Description`: Documents a query parameter.
* `@pathParam name type Description`: Documents a path parameter.
* `@headerParam name type Description`: Documents a request header parameter.

### Responses

* `@response status Type`: Documents a response status and schema type.
  * `@response 200 ArticleResource`
  * `@response 200 ArticleResource[]`
  * `@response 201 {"id": 1, "status": "created"}`
  * `@response 204 No Content`
* `@throws ExceptionClass`: Automatically infers error status codes from exception types (e.g. `ModelNotFoundException` maps to 404).

## Precedence Rules

When both inferred data and explicit annotations are present, Geni applies the following priority order:

1. **PHP 8 Attributes**: Highest priority. Overrides all other sources.
2. **PHPDoc Annotations**: Second priority. Overrides inferred data.
3. **Static Inference**: Lowest priority. Used when no explicit annotations are provided.