📝 Add JSDoc Documentation for Public APIs #6

New issue

Closed

opened 2025-10-10 09:10:34 +02:00 by jack · 0 comments

jack commented

2025-10-10 09:10:34 +02:00

Owner

🎯 Code Quality Issue

Problem

The codebase lacks comprehensive JSDoc documentation, making it harder for:

Developers to understand the API
IDEs to provide helpful tooltips
API documentation generation
Maintenance and onboarding

Proposed Solution

Add JSDoc comments to all public functions, classes, and interfaces:

Function Documentation

/**
 * Executes a database query with optional parameters
 *
 * @param sql - The SQL query to execute
 * @param params - Optional query parameters for prepared statements
 * @returns Promise resolving to query results
 * @throws {DatabaseError} If query execution fails
 * @throws {ValidationError} If SQL contains forbidden operations
 *
 * @example
 * ```typescript
 * const results = await runQuery(
 *   'SELECT * FROM users WHERE id = ?',
 *   [userId]
 * );
 * ```
 */
async function runQuery(sql: string, params?: any[]): Promise<QueryResult> {
  // ...
}

Class Documentation

/**
 * Service for managing database connections and operations
 *
 * Supports PostgreSQL, MySQL/MariaDB, and SQLite databases.
 * Automatically handles connection pooling and prepared statements.
 *
 * @example
 * ```typescript
 * const db = new DatabaseService({
 *   type: 'postgres',
 *   host: 'localhost',
 *   port: 5432
 * });
 * await db.connect();
 * ```
 */
class DatabaseService {
  // ...
}

Interface Documentation

/**
 * Configuration options for database connection
 */
interface DatabaseConfig {
  /** Database type: postgres, mysql, or sqlite */
  type: 'postgres' | 'mysql' | 'sqlite';

  /** Database host (not required for SQLite) */
  host?: string;

  /** Database port (default: 5432 for PostgreSQL, 3306 for MySQL) */
  port?: number;
}

Tools to Use

TypeDoc for generating HTML documentation
TSDoc standard for consistent documentation

Benefits

📚 Better developer experience
🔍 Improved IDE tooltips
📖 Auto-generated documentation
🎓 Easier onboarding

Priority

Medium - Improves maintainability

🤖 Generated with Claude Code

## 🎯 Code Quality Issue ### Problem The codebase lacks comprehensive JSDoc documentation, making it harder for: - Developers to understand the API - IDEs to provide helpful tooltips - API documentation generation - Maintenance and onboarding ### Proposed Solution Add JSDoc comments to all public functions, classes, and interfaces: #### Function Documentation ```typescript /** * Executes a database query with optional parameters * * @param sql - The SQL query to execute * @param params - Optional query parameters for prepared statements * @returns Promise resolving to query results * @throws {DatabaseError} If query execution fails * @throws {ValidationError} If SQL contains forbidden operations * * @example * ```typescript * const results = await runQuery( * 'SELECT * FROM users WHERE id = ?', * [userId] * ); * ``` */ async function runQuery(sql: string, params?: any[]): Promise<QueryResult> { // ... } ``` #### Class Documentation ```typescript /** * Service for managing database connections and operations * * Supports PostgreSQL, MySQL/MariaDB, and SQLite databases. * Automatically handles connection pooling and prepared statements. * * @example * ```typescript * const db = new DatabaseService({ * type: 'postgres', * host: 'localhost', * port: 5432 * }); * await db.connect(); * ``` */ class DatabaseService { // ... } ``` #### Interface Documentation ```typescript /** * Configuration options for database connection */ interface DatabaseConfig { /** Database type: postgres, mysql, or sqlite */ type: 'postgres' | 'mysql' | 'sqlite'; /** Database host (not required for SQLite) */ host?: string; /** Database port (default: 5432 for PostgreSQL, 3306 for MySQL) */ port?: number; } ``` ### Tools to Use - TypeDoc for generating HTML documentation - TSDoc standard for consistent documentation ### Benefits - 📚 Better developer experience - 🔍 Improved IDE tooltips - 📖 Auto-generated documentation - 🎓 Easier onboarding ### Priority **Medium** - Improves maintainability 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jack referenced this issue from a commit

2025-10-10 09:40:28 +02:00

📝 Add comprehensive JSDoc documentation for all public APIs

jack closed this issue

2025-10-10 09:48:20 +02:00

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

customable-mcp/browser-mcp#6

No description provided.

Rows
Columns