Creating a Documentation Template for Vue Components

{
  "title": "Creating a Documentation Template for Vue Components",
  "description": "Understand how to document Vue components effectively to promote clarity and understanding among team members.",
  "category": "Vue Cursor Rules",
  "rules": [
    {
      "name": "Component Documentation Structure",
      "description": "Ensure each Vue component includes a structured documentation block at the beginning of the file.",
      "pattern": "^(<script.*?>\\n)(/\\*\\*\\n \\*.*?\\n \\*/\\n)?",
      "replacement": "$1/**\n * Component Name: [ComponentName]\n * Description: [Brief description of the component's purpose]\n * Props:\n *   - [propName] ([type]): [description]\n * Events:\n *   - [eventName]: [description]\n * Slots:\n *   - [slotName]: [description]\n * Example Usage:\n * ```vue\n * <[ComponentName] [propName]=\\\"value\\\">\n *   <!-- slot content -->\n * </[ComponentName]>\n * ```\n */\n",
      "description": "This rule enforces the inclusion of a standardized JSDoc-style comment block at the beginning of each Vue component file, detailing the component's name, description, props, events, slots, and an example usage. This practice enhances code readability and maintainability by providing clear documentation directly within the component file."
    },
    {
      "name": "Prop Documentation",
      "description": "Document each prop with a JSDoc comment above its definition.",
      "pattern": "(props:\\s*{\\n)([^}]+)(\\n\\s*})",
      "replacement": "$1/**\n * @prop {type} propName - Description of the prop.\n */\n$2$3",
      "description": "This rule ensures that each prop within a Vue component is accompanied by a JSDoc comment, specifying its type and description. This practice aids in understanding the purpose and expected data for each prop, facilitating better collaboration and code maintenance."
    },
    {
      "name": "Event Documentation",
      "description": "Document each emitted event with a JSDoc comment above its emission.",
      "pattern": "(this\\.\\$emit\\(['\"])([^'\"]+)(['\"].*?\\))",
      "replacement": "/**\n * @event {type} eventName - Description of the event.\n */\n$1$2$3",
      "description": "This rule mandates the documentation of each event emitted by a Vue component, using JSDoc comments placed above the emission statement. Documenting events clarifies the component's communication with parent components, improving the overall understanding of the component's behavior."
    },
    {
      "name": "Slot Documentation",
      "description": "Document each slot with a JSDoc comment above its usage in the template.",
      "pattern": "(<slot\\s*name=['\"])([^'\"]+)(['\"].*?>)",
      "replacement": "<!--\n  @slot slotName - Description of the slot.\n-->\n$1$2$3",
      "description": "This rule enforces the documentation of each named slot within a Vue component's template, using HTML comments. Providing descriptions for slots helps developers understand where and how to insert content into the component, enhancing usability and integration."
    },
    {
      "name": "Example Usage Documentation",
      "description": "Include an example usage section in the component's documentation block.",
      "pattern": "(\\*\\s*Description:.*?\\n)(\\*\\s*Props:.*?\\n)(\\*\\s*Events:.*?\\n)(\\*\\s*Slots:.*?\\n)",
      "replacement": "$1$2$3$4 * Example Usage:\n * ```vue\n * <[ComponentName] [propName]=\\\"value\\\">\n *   <!-- slot content -->\n * </[ComponentName]>\n * ```\n",
      "description": "This rule ensures that each Vue component's documentation block includes an 'Example Usage' section, providing a practical example of how to implement the component. Including usage examples aids developers in quickly understanding how to utilize the component in different contexts."
    }
  ]
}