codeforge-dev 1.5.8 → 1.8.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/documentation-patterns/references/api-doc-templates.md

@@ -0,0 +1,221 @@
+# API Documentation Templates
+
+## REST Endpoint Documentation
+
+Use this template for each API endpoint:
+
+### Template
+
+```markdown
+## [Method] [Path]
+
+[One-sentence description of what this endpoint does.]
+
+### Request
+
+**URL Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | string | Yes | The resource identifier |
+
+**Query Parameters:**
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `limit` | integer | No | 20 | Maximum results to return (1-100) |
+| `cursor` | string | No | — | Pagination cursor from previous response |
+
+**Request Body:**
+
+| Field | Type | Required | Description | Constraints |
+|-------|------|----------|-------------|-------------|
+| `name` | string | Yes | Display name | 1-100 characters |
+| `email` | string | Yes | Email address | Valid email format |
+
+**Example Request:**
+
+\```bash
+curl -X POST https://api.example.com/v1/users \
+  -H "Authorization: Bearer sk-abc123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Jane Doe",
+    "email": "jane@example.com"
+  }'
+\```
+
+### Response
+
+**Success (201 Created):**
+
+\```json
+{
+  "id": "usr_abc123",
+  "name": "Jane Doe",
+  "email": "jane@example.com",
+  "created_at": "2024-01-15T10:30:00Z"
+}
+\```
+
+**Error Responses:**
+
+| Status | Type | When |
+|--------|------|------|
+| 400 | validation-error | Invalid request body |
+| 401 | authentication-required | Missing or expired token |
+| 409 | resource-conflict | Email already registered |
+| 429 | rate-limit-exceeded | Too many requests |
+```
+
+---
+
+## Parameter Table Format
+
+Always include these columns for parameters:
+
+| Column | Purpose |
+|--------|---------|
+| **Name** | Parameter name as it appears in code |
+| **Type** | Data type (string, integer, boolean, array, object) |
+| **Required** | Yes / No |
+| **Default** | Default value if optional (— if none) |
+| **Description** | What this parameter does |
+| **Constraints** | Validation rules (min/max, regex, enum values) |
+
+### Example
+
+| Name | Type | Required | Default | Description | Constraints |
+|------|------|----------|---------|-------------|-------------|
+| `page_size` | integer | No | 20 | Results per page | 1–100 |
+| `status` | string | No | — | Filter by status | `active`, `inactive`, `pending` |
+| `created_after` | string | No | — | Filter by creation date | ISO 8601 format |
+
+---
+
+## Request / Response Examples
+
+### curl
+
+```bash
+curl -X GET "https://api.example.com/v1/users?status=active&limit=10" \
+  -H "Authorization: Bearer sk-abc123" \
+  -H "Accept: application/json"
+```
+
+### httpie
+
+```bash
+http GET https://api.example.com/v1/users \
+  status==active limit==10 \
+  Authorization:"Bearer sk-abc123"
+```
+
+### Python (requests)
+
+```python
+import requests
+
+response = requests.get(
+    "https://api.example.com/v1/users",
+    params={"status": "active", "limit": 10},
+    headers={"Authorization": "Bearer sk-abc123"},
+)
+data = response.json()
+```
+
+---
+
+## Error Response Documentation
+
+Document every error code an endpoint can return:
+
+```markdown
+### Errors
+
+| Status | Error Type | Description | Example Detail |
+|--------|-----------|-------------|---------------|
+| 400 | `validation-error` | Request body is malformed | "Missing required field: 'name'" |
+| 401 | `authentication-required` | Token missing or expired | "Access token has expired" |
+| 403 | `insufficient-permissions` | Valid token, wrong scope | "Requires 'admin' scope" |
+| 404 | `resource-not-found` | Resource doesn't exist | "No user with ID 'usr_999'" |
+| 409 | `resource-conflict` | Duplicate or state conflict | "Email already registered" |
+| 422 | `unprocessable-entity` | Valid syntax, invalid data | "Age must be positive" |
+| 429 | `rate-limit-exceeded` | Too many requests | "Retry after 30 seconds" |
+```
+
+---
+
+## OpenAPI / Swagger Annotations
+
+### Python (FastAPI)
+
+```python
+@router.post(
+    "/users",
+    response_model=UserResponse,
+    status_code=201,
+    summary="Create a new user",
+    description="Registers a new user account with the provided details.",
+    responses={
+        409: {"description": "Email already registered"},
+        422: {"description": "Validation error"},
+    },
+)
+async def create_user(user: UserCreate) -> UserResponse:
+```
+
+### TypeScript (NestJS / Swagger)
+
+```typescript
+@ApiOperation({ summary: 'Create a new user' })
+@ApiResponse({ status: 201, description: 'User created', type: UserResponse })
+@ApiResponse({ status: 409, description: 'Email already registered' })
+@Post('users')
+async createUser(@Body() dto: CreateUserDto): Promise<UserResponse> {
+```
+
+---
+
+## Mermaid Diagram Quick Reference
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant A as API
+    participant D as Database
+    C->>A: POST /users
+    A->>D: INSERT user
+    D-->>A: user record
+    A-->>C: 201 Created
+```
+
+### Flowchart
+
+```mermaid
+flowchart TD
+    A[Request] --> B{Authenticated?}
+    B -->|No| C[401 Unauthorized]
+    B -->|Yes| D{Valid Input?}
+    D -->|No| E[422 Validation Error]
+    D -->|Yes| F[Process Request]
+    F --> G[200 OK]
+```
+
+### Entity Relationship
+
+```mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ LINE_ITEM : contains
+    PRODUCT ||--o{ LINE_ITEM : "ordered in"
+```
+
+### Tips
+
+- Keep diagrams **under 10 nodes**. Split complex flows into multiple diagrams.
+- Use descriptive labels on arrows (not just `-->` but `-->|description|`).
+- Mermaid renders in GitHub, VS Code preview, and most documentation platforms.
+- For architecture diagrams, prefer `flowchart` over `graph` (flowchart is the newer syntax).

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/documentation-patterns/references/docstring-formats.md

@@ -0,0 +1,296 @@
+# Docstring Format Reference
+
+Complete templates for inline documentation across languages. Detect the project's existing style before adding new docstrings.
+
+---
+
+## Python
+
+### Google-Style (Recommended Default)
+
+Detection pattern: `Grep: "Args:"` or `Grep: "Returns:"` in `.py` files.
+
+```python
+def process_payment(amount: float, currency: str, customer_id: str) -> PaymentResult:
+    """Process a payment for the given customer.
+
+    Validates the amount, charges the customer's default payment method,
+    and records the transaction in the payment ledger.
+
+    Args:
+        amount: Payment amount in the smallest currency unit (e.g., cents).
+            Must be positive.
+        currency: ISO 4217 currency code (e.g., "usd", "eur").
+        customer_id: The unique customer identifier from the auth system.
+
+    Returns:
+        PaymentResult with transaction ID, status, and timestamp.
+
+    Raises:
+        InvalidAmountError: If amount is negative or zero.
+        CustomerNotFoundError: If customer_id doesn't match any customer.
+        PaymentGatewayError: If the external payment provider is unreachable.
+
+    Example:
+        >>> result = process_payment(1500, "usd", "cust_abc123")
+        >>> result.status
+        'completed'
+    """
+```
+
+### NumPy-Style
+
+Detection pattern: `Grep: "Parameters\n----------"` (multiline) or `Grep: "----------"` in docstrings.
+
+```python
+def interpolate(x, y, method="linear"):
+    """Interpolate data points using the specified method.
+
+    Parameters
+    ----------
+    x : array_like
+        The x-coordinates of the data points.
+    y : array_like
+        The y-coordinates of the data points. Must have the same length as `x`.
+    method : str, optional
+        Interpolation method. One of 'linear', 'cubic', 'nearest'.
+        Default is 'linear'.
+
+    Returns
+    -------
+    callable
+        An interpolation function that accepts x values and returns
+        interpolated y values.
+
+    Raises
+    ------
+    ValueError
+        If `x` and `y` have different lengths.
+
+    Examples
+    --------
+    >>> f = interpolate([0, 1, 2], [0, 1, 4], method='cubic')
+    >>> f(1.5)
+    2.25
+    """
+```
+
+### Sphinx / reStructuredText
+
+Detection pattern: `Grep: ":param "` or `Grep: ":type "` in `.py` files.
+
+```python
+def connect(host, port, timeout=30):
+    """Connect to the remote server.
+
+    Establishes a TCP connection with configurable timeout.
+
+    :param host: Server hostname or IP address.
+    :type host: str
+    :param port: Server port number (1-65535).
+    :type port: int
+    :param timeout: Connection timeout in seconds. Defaults to 30.
+    :type timeout: int
+    :returns: Active connection handle.
+    :rtype: Connection
+    :raises ConnectionError: If the server is unreachable.
+    :raises ValueError: If port is out of valid range.
+    """
+```
+
+### Module and Class Docstrings
+
+```python
+"""Payment processing module.
+
+Handles payment creation, validation, and gateway communication.
+Supports Stripe and PayPal providers via the adapter pattern.
+
+See `src/payments/adapters/` for provider implementations.
+"""
+
+
+class PaymentProcessor:
+    """Orchestrates payment workflows across multiple providers.
+
+    Manages provider selection, retry logic, and transaction recording.
+    Uses the strategy pattern to delegate provider-specific logic.
+
+    Attributes:
+        default_provider: Name of the fallback payment provider.
+        max_retries: Maximum retry attempts for failed transactions.
+    """
+```
+
+---
+
+## TypeScript / JavaScript
+
+### JSDoc
+
+Detection pattern: `Grep: "@param "` or `Grep: "@returns"` in `.ts` or `.js` files.
+
+```typescript
+/**
+ * Process a payment for the given customer.
+ *
+ * Validates the amount, charges the customer's default payment method,
+ * and records the transaction.
+ *
+ * @param amount - Payment amount in cents (must be positive)
+ * @param currency - ISO 4217 currency code (e.g., "usd", "eur")
+ * @param customerId - The unique customer identifier
+ * @returns Payment result with transaction ID and status
+ * @throws {InvalidAmountError} If amount is negative or zero
+ * @throws {CustomerNotFoundError} If customerId doesn't match any customer
+ *
+ * @example
+ * ```typescript
+ * const result = await processPayment(1500, "usd", "cust_abc123");
+ * console.log(result.status); // "completed"
+ * ```
+ */
+async function processPayment(
+  amount: number,
+  currency: string,
+  customerId: string
+): Promise<PaymentResult> {
+```
+
+### TSDoc
+
+TSDoc is a stricter subset of JSDoc used by TypeScript-focused projects.
+
+Key differences from JSDoc:
+- Uses `{@link ClassName}` for references (not `{@see}`)
+- `@param name -` format (with dash separator)
+- `@throws` without type braces (types are in TypeScript)
+
+```typescript
+/**
+ * Fetches user data from the API.
+ *
+ * @param userId - The user's unique identifier
+ * @param options - Request configuration
+ * @returns The user object, or `undefined` if not found
+ *
+ * @remarks
+ * This method caches results for 5 minutes. Use {@link invalidateCache}
+ * to force a fresh fetch.
+ */
+```
+
+### Module / File Headers
+
+```typescript
+/**
+ * @module payments
+ *
+ * Payment processing module handling Stripe and PayPal integrations.
+ * Entry point: {@link PaymentProcessor.process}
+ */
+```
+
+---
+
+## Go (godoc)
+
+Detection pattern: Comments starting with the function/type name: `Grep: "^// [A-Z]"` before `func` or `type` declarations.
+
+```go
+// ProcessPayment charges the customer's default payment method.
+// Amount is in the smallest currency unit (e.g., cents for USD).
+// Currency must be a valid ISO 4217 code.
+//
+// Returns the transaction result or an error if the charge fails.
+// Possible errors: ErrInvalidAmount, ErrCustomerNotFound, ErrGatewayUnavailable.
+func ProcessPayment(amount int64, currency string, customerID string) (*PaymentResult, error) {
+```
+
+### Package Comments
+
+```go
+// Package payments provides payment processing across multiple providers.
+//
+// It supports Stripe and PayPal via pluggable adapters. Use NewProcessor
+// to create a processor with the desired provider configuration.
+//
+// Example:
+//
+//	p := payments.NewProcessor(payments.WithStripe(apiKey))
+//	result, err := p.Process(ctx, 1500, "usd", "cust_123")
+package payments
+```
+
+### godoc Conventions
+
+- First sentence starts with the name being documented: "ProcessPayment charges..."
+- Use complete sentences with proper punctuation.
+- Code examples use tab-indented blocks (no triple backticks).
+- Document exported (capitalized) identifiers only.
+
+---
+
+## Rust (rustdoc)
+
+Detection pattern: `Grep: "/// "` or `Grep: "//! "` in `.rs` files.
+
+```rust
+/// Process a payment for the given customer.
+///
+/// Validates the amount, charges the customer's default payment method,
+/// and records the transaction in the payment ledger.
+///
+/// # Arguments
+///
+/// * `amount` - Payment amount in cents (must be positive)
+/// * `currency` - ISO 4217 currency code (e.g., "usd", "eur")
+/// * `customer_id` - The unique customer identifier
+///
+/// # Returns
+///
+/// A `PaymentResult` with transaction ID, status, and timestamp.
+///
+/// # Errors
+///
+/// Returns `PaymentError::InvalidAmount` if the amount is zero or negative.
+/// Returns `PaymentError::CustomerNotFound` if the customer ID is invalid.
+///
+/// # Examples
+///
+/// ```
+/// let result = process_payment(1500, "usd", "cust_abc123")?;
+/// assert_eq!(result.status, PaymentStatus::Completed);
+/// ```
+///
+/// # Panics
+///
+/// Panics if the payment gateway client is not initialized. Call
+/// `init_gateway()` before using this function.
+pub fn process_payment(amount: u64, currency: &str, customer_id: &str) -> Result<PaymentResult, PaymentError> {
+```
+
+### Module Documentation
+
+```rust
+//! Payment processing module.
+//!
+//! Handles payment creation, validation, and gateway communication.
+//! Supports Stripe and PayPal providers via the adapter pattern.
+//!
+//! # Overview
+//!
+//! Use [`PaymentProcessor::new`] to create a processor, then call
+//! [`PaymentProcessor::process`] to execute a payment.
+```
+
+### Sections Convention
+
+| Section | When to Use |
+|---------|------------|
+| `# Arguments` | All public functions with parameters |
+| `# Returns` | Functions that return non-unit types |
+| `# Errors` | Functions that return `Result` |
+| `# Panics` | Functions that can panic |
+| `# Safety` | Unsafe functions — document invariants |
+| `# Examples` | Always for public API |