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:

/**
 * 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:

/**
 * 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:

/**
 * 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:

/**
 * 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

// 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:

// 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