Utilizing JSDoc for Enhanced Code Documentation

{
  "title": "Utilizing JSDoc for Enhanced Code Documentation",
  "description": "Implement JSDoc to create standard, readable documentation for JavaScript functions and modules.",
  "category": "JavaScript Cursor Rules",
  "rules": [
    {
      "name": "Mandatory JSDoc Comments",
      "description": "All functions, classes, and modules must include JSDoc comments to describe their purpose, parameters, and return values.",
      "examples": [
        {
          "before": "function add(a, b) { return a + b; }",
          "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 a and b.\n */\nfunction add(a, b) { return a + b; }"
        }
      ]
    },
    {
      "name": "Consistent Use of JSDoc Tags",
      "description": "Utilize standard JSDoc tags such as @param, @returns, @throws, and @deprecated to provide structured information.",
      "examples": [
        {
          "before": "function divide(a, b) { if (b === 0) throw new Error('Division by zero'); return a / b; }",
          "after": "/**\n * Divides two numbers.\n * @param {number} a - The dividend.\n * @param {number} b - The divisor.\n * @returns {number} The quotient of a and b.\n * @throws {Error} Throws an error if b is zero.\n */\nfunction divide(a, b) { if (b === 0) throw new Error('Division by zero'); return a / b; }"
        }
      ]
    },
    {
      "name": "Documenting Object Structures",
      "description": "Use @typedef to define complex object structures and reference them in function parameters.",
      "examples": [
        {
          "before": "function createUser(user) { /* implementation */ }",
          "after": "/**\n * @typedef {Object} User\n * @property {string} firstName - The user's first name.\n * @property {string} lastName - The user's last name.\n * @property {number} age - The user's age.\n */\n\n/**\n * Creates a new user.\n * @param {User} user - The user object.\n */\nfunction createUser(user) { /* implementation */ }"
        }
      ]
    },
    {
      "name": "Class Documentation",
      "description": "Provide JSDoc comments for classes, including constructor parameters and method descriptions.",
      "examples": [
        {
          "before": "class Rectangle { constructor(width, height) { this.width = width; this.height = height; } area() { return this.width * this.height; } }",
          "after": "/**\n * Represents a rectangle.\n */\nclass Rectangle {\n  /**\n   * Creates a rectangle.\n   * @param {number} width - The width of the rectangle.\n   * @param {number} height - The height of the rectangle.\n   */\n  constructor(width, height) { this.width = width; this.height = height; }\n\n  /**\n   * Calculates the area of the rectangle.\n   * @returns {number} The area of the rectangle.\n   */\n  area() { return this.width * this.height; }\n}"
        }
      ]
    },
    {
      "name": "Avoid Redundant Comments",
      "description": "Ensure comments provide additional insight and do not merely repeat the code.",
      "examples": [
        {
          "before": "/**\n * Adds two numbers.\n * @param {number} a - The first number.\n * @param {number} b - The second number.\n * @returns {number} The sum of a and b.\n */\nfunction add(a, b) { return a + b; }",
          "after": "/**\n * Calculates the sum of two numbers.\n * @param {number} a - The first number.\n * @param {number} b - The second number.\n * @returns {number} The sum of a and b.\n */\nfunction add(a, b) { return a + b; }"
        }
      ]
    }
  ]
}