Creating Documentation Standards for JavaScript Projects

{
  "title": "Creating Documentation Standards for JavaScript Projects",
  "description": "Establish comprehensive documentation practices that support team collaboration and knowledge sharing across JavaScript projects.",
  "category": "JavaScript Cursor Rules",
  "rules": [
    {
      "name": "Use JSDoc for Function Documentation",
      "description": "Annotate all functions and methods with JSDoc comments to provide clear descriptions, parameter details, and return types.",
      "examples": [
        {
          "before": "function add(a, b) {\n  return a + b;\n}",
          "after": "/**\n * Adds two numbers together.\n * @param {number} a - The first number.\n * @param {number} b - The second number.\n * @returns {number} The sum of the two numbers.\n */\nfunction add(a, b) {\n  return a + b;\n}"
        }
      ]
    },
    {
      "name": "Document Classes and Constructors",
      "description": "Provide JSDoc comments for all classes and their constructors, detailing their purpose and usage.",
      "examples": [
        {
          "before": "class User {\n  constructor(name, email) {\n    this.name = name;\n    this.email = email;\n  }\n}",
          "after": "/**\n * Represents a user.\n * @class\n */\nclass User {\n  /**\n   * Creates an instance of User.\n   * @param {string} name - The user's name.\n   * @param {string} email - The user's email address.\n   */\n  constructor(name, email) {\n    this.name = name;\n    this.email = email;\n  }\n}"
        }
      ]
    },
    {
      "name": "Include Module-Level Documentation",
      "description": "At the beginning of each module, include a JSDoc comment summarizing the module's purpose and functionality.",
      "examples": [
        {
          "before": "// utility.js\nfunction helper() {\n  // ...\n}",
          "after": "/**\n * Utility functions for common operations.\n * @module utility\n */\n\nfunction helper() {\n  // ...\n}"
        }
      ]
    },
    {
      "name": "Use Inline Comments for Complex Code",
      "description": "Add inline comments to explain complex logic or algorithms within functions to enhance readability.",
      "examples": [
        {
          "before": "function calculateFactorial(n) {\n  if (n === 0) return 1;\n  return n * calculateFactorial(n - 1);\n}",
          "after": "function calculateFactorial(n) {\n  // Base case: factorial of 0 is 1\n  if (n === 0) return 1;\n  // Recursive case: n! = n * (n-1)!\n  return n * calculateFactorial(n - 1);\n}"
        }
      ]
    },
    {
      "name": "Document Object Properties",
      "description": "Use JSDoc to describe the properties of objects, especially for complex data structures.",
      "examples": [
        {
          "before": "const user = {\n  name: 'John Doe',\n  email: 'john.doe@example.com'\n};",
          "after": "/**\n * @typedef {Object} User\n * @property {string} name - The user's name.\n * @property {string} email - The user's email address.\n */\n\n/** @type {User} */\nconst user = {\n  name: 'John Doe',\n  email: 'john.doe@example.com'\n};"
        }
      ]
    },
    {
      "name": "Maintain Updated README Files",
      "description": "Ensure that each project contains a README file with up-to-date information on setup, usage, and contribution guidelines.",
      "examples": [
        {
          "before": "No README file present.",
          "after": "# Project Name\n\n## Description\n\nA brief description of the project.\n\n## Installation\n\nSteps to install the project.\n\n## Usage\n\nInstructions on how to use the project.\n\n## Contributing\n\nGuidelines for contributing to the project."
        }
      ]
    },
    {
      "name": "Use Consistent Comment Style",
      "description": "Adopt a consistent style for comments throughout the codebase to improve readability and maintainability.",
      "examples": [
        {
          "before": "//This function does something\nfunction doSomething() {\n  //do stuff\n}",
          "after": "// This function performs a specific task.\nfunction doSomething() {\n  // Execute the task.\n}"
        }
      ]
    },
    {
      "name": "Leverage TypeScript for Enhanced Documentation",
      "description": "Utilize TypeScript to enforce type safety and generate comprehensive documentation using tools like TSDoc.",
      "examples": [
        {
          "before": "function greet(name) {\n  return 'Hello, ' + name;\n}",
          "after": "/**\n * Greets a user by name.\n * @param {string} name - The name of the user.\n * @returns {string} A greeting message.\n */\nfunction greet(name: string): string {\n  return `Hello, ${name}`;\n}"
        }
      ]
    }
  ]
}