Documentation Requirements¶

MANDATORY Documentation Updates¶

• Code Documentation: Complex types and interfaces MUST include JSDoc comments.
• API Documentation: All API routes should be documented with request/response examples.

Documentation Structure¶

Project Documentation¶

.cursor/rules:

• Main project documentation, setup instructions, and overview.
• Detailed documentation organized by feature/system.
• Learning Management System specific documentation.
• Canonical data-listing behavior is documented in 055-data-listing-patterns.mdc.

Code Documentation¶

• JSDoc Comments: Required for complex types, interfaces, and functions.
• Inline Comments: Use for non-obvious code logic.
• Type Documentation: Document complex type definitions.

README.md Maintenance¶

When to Update README.md¶

• Adding new features or systems.
• Changing setup or installation procedures.
• Adding new environment variables.
• Updating dependencies or requirements.
• Adding new documentation files to .cursor/rules.

README.md Structure¶

# Project Title

## Overview

Brief description of the project.

## Getting Started

Setup and installation instructions.

## Documentation

Links to detailed documentation in `.cursor/rules`.

## Development

Development guidelines and practices.

## Contributing

How to contribute to the project.

Code Documentation Standards¶

JSDoc for Types¶

/
 * Represents a course enrollment with user and course information.
 *
 * @property userId - The Auth.js user id (matches `users.id` in the database).
 * @property courseId - The document ID of the enrolled course.
 * @property status - The enrollment status (pending, enrolled, completed).
 * @property enrolledAt - Timestamp when the enrollment was created.
 * @property completedAt - Optional timestamp when the course was completed.
 */
export interface Enrollment {
  userId: string;
  courseId: string;
  status: 'pending' | 'enrolled' | 'completed';
  enrolledAt: Date;
  completedAt?: Date;
}

JSDoc for Functions¶

/
 * Calculates pagination data for course entries.
 *
 * Flattens hierarchical course entries into a linear sequence and
 * determines the previous and next entries based on the current entry.
 *
 * @param entries - Array of course entries with hierarchical structure.
 * @param currentSlug - Slug of the current entry.
 * @param courseSlug - Slug of the parent course.
 * @param segments - Optional path segments for hierarchical entries.
 * @returns Pagination data with previous and next entry information.
 *
 * @example
 * ```ts
 * const pagination = getEntryPagination(entries, 'intro-css', 'intro-web-dev');
 * // Returns: { previous: {...}, next: {...} }
 * ```
 */
export function getEntryPagination(entries: CourseEntry[], currentSlug: string, courseSlug: string, segments?: string[]): PaginationData {
  // Implementation
}

JSDoc for Components¶

/
 * Breadcrumb navigation component for course entries.
 *
 * Displays hierarchical navigation path showing the course structure
 * and current entry location. Supports keyboard navigation and
 * accessibility features.
 *
 * @param breadcrumbs - Array of breadcrumb items to display.
 * @param className - Optional additional CSS classes.
 *
 * @example
 * ```tsx
 * <Breadcrumbs
 *   breadcrumbs={[
 *     { title: 'Course', href: '/learn/course/intro' },
 *     { title: 'Module', href: '/learn/course/intro/module' },
 *     { title: 'Current', href: '/learn/course/intro/module/current' }
 *   ]}
 * />
 * ```
 */
export function Breadcrumbs({ breadcrumbs, className }: BreadcrumbsProps) {
  // Implementation
}

Documentation Files¶

Markdown Documentation¶

• Use clear headings and structure.
• Include code examples where helpful.
• Link to related documentation.
• Keep documentation up-to-date with code changes.

API Documentation¶

• Document all API endpoints.
• Include request/response examples.
• Document error responses.
• Include authentication requirements.

Inline Comments¶

When to Use Inline Comments¶

• Explain non-obvious business logic.
• Document workarounds or temporary solutions.
• Explain complex algorithms.
• Note important implementation details.

Comment Style¶

// Good: Explains why, not what
// Filter published courses only to ensure static generation
// includes only publicly accessible content.
const publishedCourses = courses.filter((course) => course.published);

// Bad: States the obvious
// Filter courses.
const publishedCourses = courses.filter((course) => course.published);

// Note: learnEntry documents do NOT have a published field.
// Entry visibility is controlled at the course level.

Documentation Maintenance¶

Keeping Documentation Current¶

• Update documentation when code changes.
• Remove obsolete documentation.
• Review documentation during code reviews.
• Keep examples accurate and working.

Documentation Review¶

• Include documentation in code reviews.
• Verify examples work correctly.
• Check for broken links.
• Ensure clarity and completeness.

Best Practices¶

• Write documentation as you write code.
• Keep documentation close to code (co-located).
• Use clear, concise language.
• Include examples and use cases.
• Keep documentation organized and searchable.