Sankofa/docs/guides/CODE_DOCUMENTATION_GUIDE.md

# Code Documentation Guide

This guide outlines the standards and best practices for documenting code in the Sankofa Phoenix project.

## JSDoc Standards

### Function Documentation

All public functions should include JSDoc comments with:

- Description of what the function does
- `@param` tags for each parameter
- `@returns` tag describing the return value
- `@throws` tags for exceptions that may be thrown
- `@example` tag with usage example (for complex functions)

**Example:**

```typescript
/**
 * Authenticate a user and return JWT token
 * 
 * @param email - User email address
 * @param password - User password
 * @returns Authentication payload with JWT token and user information
 * @throws {AuthenticationError} If credentials are invalid
 * @example
 * ```typescript
 * const result = await login('user@example.com', 'password123');
 * console.log(result.token); // JWT token
 * ```
 */
export async function login(email: string, password: string): Promise<AuthPayload> {
  // implementation
}
```

### Class Documentation

Classes should include:

- Description of the class purpose
- `@example` tag showing basic usage

**Example:**

```typescript
/**
 * Proxmox VE Infrastructure Adapter
 * 
 * Implements the InfrastructureAdapter interface for Proxmox VE infrastructure.
 * Provides resource discovery, creation, update, deletion, metrics, and health checks.
 * 
 * @example
 * ```typescript
 * const adapter = new ProxmoxAdapter({
 *   apiUrl: 'https://proxmox.example.com:8006',
 *   apiToken: 'token-id=...'
 * });
 * const resources = await adapter.discoverResources();
 * ```
 */
export class ProxmoxAdapter implements InfrastructureAdapter {
  // implementation
}
```

### Interface Documentation

Complex interfaces should include documentation:

```typescript
/**
 * Resource filter criteria for querying resources
 * 
 * @property type - Filter by resource type (e.g., 'VM', 'CONTAINER')
 * @property status - Filter by resource status (e.g., 'RUNNING', 'STOPPED')
 * @property siteId - Filter by site ID
 * @property tenantId - Filter by tenant ID
 */
export interface ResourceFilter {
  type?: string
  status?: string
  siteId?: string
  tenantId?: string
}
```

### Method Documentation

Class methods should follow the same pattern as functions:

```typescript
/**
 * Discover all resources across all Proxmox nodes
 * 
 * @returns Array of normalized resources (VMs) from all nodes
 * @throws {Error} If API connection fails or nodes cannot be retrieved
 * @example
 * ```typescript
 * const resources = await adapter.discoverResources();
 * console.log(`Found ${resources.length} VMs`);
 * ```
 */
async discoverResources(): Promise<NormalizedResource[]> {
  // implementation
}
```

## Inline Comments

### When to Use Inline Comments

- **Complex logic**: Explain non-obvious algorithms or business rules
- **Workarounds**: Document temporary fixes or known issues
- **Performance optimizations**: Explain why a particular approach was chosen
- **Business rules**: Document domain-specific logic

### Comment Style

```typescript
// Good: Explains why, not what
// Tenant-aware filtering (superior to Azure multi-tenancy)
if (context.tenantContext) {
  // System admins can see all resources
  if (context.tenantContext.isSystemAdmin) {
    // No filtering needed
  } else if (context.tenantContext.tenantId) {
    // Filter by tenant ID
    query += ` AND r.tenant_id = $${paramCount}`
  }
}

// Bad: States the obvious
// Loop through nodes
for (const node of nodes) {
  // Get VMs
  const vms = await this.getVMs(node.node)
}
```

## TODO Comments

Use TODO comments for known improvements:

```typescript
// TODO: Add rate limiting to prevent API abuse
// TODO: Implement caching for frequently accessed resources
// FIXME: This workaround should be removed when upstream issue is fixed
```

## Documentation Checklist

When adding new code, ensure:

- [ ] Public functions have JSDoc comments
- [ ] Complex private functions have inline comments
- [ ] Classes have class-level documentation
- [ ] Interfaces have documentation for complex types
- [ ] Examples are provided for public APIs
- [ ] Error cases are documented with `@throws`
- [ ] Complex algorithms have explanatory comments
- [ ] Business rules are documented

## Tools

- **TypeScript**: Built-in JSDoc support
- **VS Code**: JSDoc snippets and IntelliSense
- **tsdoc**: Standard for TypeScript documentation comments

---

**Last Updated**: 2025-01-09