// You type:
/**
 * 
 */
function calculateTotal(items: CartItem[], taxRate: number): number {

/**
 * Calculates the total price including tax for an array of cart items.
 * @param items - Array of cart items to calculate totals for
 * @param taxRate - Tax rate as a decimal (e.g., 0.08 for 8%)
 * @returns The total price with tax applied
 */
function calculateTotal(items: CartItem[], taxRate: number): number {

// Claude correctly generates:
/**
 * Processes user authentication tokens and refreshes them if expired.
 * @template T - The type of user data stored in the token
 * @param token - The JWT token string to validate
 * @param refreshToken - The refresh token used when access token expires
 * @returns Promise resolving to authenticated user data or null if invalid
 * @throws {AuthError} When both tokens are invalid or expired
 * @example
 * const user = await authenticateUser('eyJhbG...', 'refresh_abc123');
 * if (user) console.log(`Welcome, ${user.name}`);
 */
async function authenticateUser<T extends UserData>(
  token: string, 
  refreshToken: string
): Promise<T | null> {

/**
 * Fetches and aggregates analytics data from multiple sources.
 * 
 * This function retrieves data from Google Analytics, Mixpanel, and
 * your internal tracking system, then combines the results into a
 * unified dashboard view.
 * 
 * @param config - Configuration object specifying data sources and date range
 * @param sources - Array of analytics platforms to query (defaults to all)
 * @returns Promise resolving to aggregated analytics results
 * @example
 * const results = await fetchAnalytics({
 *   startDate: '2026-01-01',
 *   endDate: '2026-03-01',
 *   metrics: ['pageviews', 'conversions', 'revenue']
 * }, ['google', 'mixpanel']);
 * 
 * @remarks
 * - Requires API keys to be configured in environment variables
 * - Rate limits apply per analytics platform
 * - Large date ranges may take longer to process
 */

// Poor type hints — Copilot generates vague docs
function transform(data, processor) { }

// Explicit types — Copilot generates comprehensive docs
/**
 * Transforms input data using a stateful processor function.
 * @template T - The input data type
 * @template U - The output data type
 * @template S - The processor state type
 * @param data - Array of items to transform
 * @param processor - Function with internal state managing the transformation
 * @returns Promise resolving to transformed data array
 * @example
 * const result = await transform(
 *   [1, 2, 3],
 *   createProcessor({ batchSize: 10 })
 * );
 */
function transform<T, U, S>(
  data: T[],
  processor: StatefulProcessor<T, U, S>
): Promise<U[]> { }

// Cursor generates the most complete async documentation
/**
 * Fetches user data asynchronously with automatic retry on failure.
 * Implements exponential backoff for transient errors.
 *
 * @param userId - The numeric ID of the user to fetch
 * @param maxRetries - Maximum number of retry attempts (default: 3)
 * @returns Promise that resolves to user object or rejects with FetchError
 * @throws {FetchError} When all retries are exhausted
 * @throws {ValidationError} When userId is invalid
 * @remarks
 * - Timeouts after 5 seconds per request
 * - Does not retry on 4xx client errors
 * - Logs retry attempts to stderr
 */
async function fetchUserWithRetry(
  userId: number,
  maxRetries: number = 3
): Promise<User> { }

// Claude handles callback documentation best
/**
 * Registers an event listener with automatic cleanup and type narrowing.
 * @template T - The event data structure type
 * @param eventName - Name of the event to listen for
 * @param handler - Function invoked when event fires, receives event data
 * @param options - Configuration including priority and one-time-only flag
 * @returns Unsubscribe function to remove this specific listener
 * @example
 * const unsubscribe = onEvent('user:updated', (data) => {
 *   console.log('User updated:', data.userId);
 * }, { once: true });
 *
 * // Later: unsubscribe();
 */
function onEvent<T>(
  eventName: string,
  handler: (data: T) => void,
  options?: { once?: boolean; priority?: number }
): () => void { }

// Test file to evaluate documentation quality
const MODELS = {
  copilot: 'GitHub Copilot',
  claude: 'Claude via Cursor',
  gpt4: 'ChatGPT-4',
  codeium: 'Codeium'
};

const TEST_FUNCTIONS = [
  { name: 'calculateDistance', complexity: 'simple' },
  { name: 'asyncPipelineProcessor', complexity: 'complex' },
  { name: 'reduceWithSideEffects', complexity: 'medium' },
];

// Scoring rubric
const SCORE_CRITERIA = {
  'mentions_parameters': 10,
  'explains_return_type': 10,
  'documents_errors': 10,
  'includes_example': 10,
  'explains_side_effects': 10,
};

/**
 * Handles different response types from the API.
 * Use type guards to narrow the response before accessing type-specific fields.
 *
 * @example
 * const response = await fetchData();
 * if (response.type === 'success') {
 *   console.log(response.data); // Safe to access data
 * } else {
 *   console.error(response.error); // Safe to access error
 * }
 */
type ApiResponse<T> =
  | { type: 'success'; data: T }
  | { type: 'error'; error: string };

/**
 * Overload 1: Query with object filter.
 * @param table - Table name to query
 * @param filter - Object with field-value pairs for filtering
 * @returns Matching records
 */
export function query<T>(
  table: string,
  filter: Record<string, unknown>
): T[];

/**
 * Overload 2: Query with SQL predicate.
 * @param table - Table name to query
 * @param predicate - SQL WHERE clause as string
 * @returns Matching records
 */
export function query<T>(
  table: string,
  predicate: string
): T[];

// Implementation (no doc comment needed)
export function query<T>(
  table: string,
  filterOrPredicate: string | Record<string, unknown>
): T[] {
  // ...
}