+ {/* Kitchen Sink Example */}
+
+
+
+
+ Kitchen Sink Example
+
+
+
+ A comprehensive example showcasing multiple JSDoc features in one code block
+
+
+
+
+
+
+
+ {/* Navigation Grid */}
+
+
Explore JSDoc Sections
+
+ Choose a section to dive deeper into specific JSDoc features
+
-
-
- {/* Sidebar Navigation */}
-
-
- {/* Main Content */}
-
-
- {/* Kitchen Sink Example */}
-
-
-
-
- Kitchen Sink Example
-
-
-
- A comprehensive example showcasing multiple JSDoc features in one code block
-
-
-
-
-
-
-
- {/* Section Header */}
-
-
- {jsdocData[activeSection as keyof typeof jsdocData]?.title || "Section"}
-
-
- {jsdocData[activeSection as keyof typeof jsdocData]?.description || "Documentation section"}
-
-
-
- {/* Content Cards */}
-
- {jsdocData[activeSection as keyof typeof jsdocData]?.items.map((item, index) => (
-
-
-
-
-
- {item.tag}
-
-
+
+ {navigationSections.map((section) => {
+ const Icon = section.icon
+ return (
+
+
+
+
+
- {item.description}
+
+ {section.title}
+
+
+ {section.description}
+
-
- {/* Syntax */}
-
-
Syntax:
-
- {item.syntax}
-
-
-
-
-
- {/* Example with Syntax Highlighting */}
-
-
Example:
-
-
+
+
- )) || []}
+
+ )
+ })}
+
+
+ {/* Quick Reference */}
+
+
+
+
+ Quick Reference
+
+
+ Essential JSDoc tags you'll use most frequently
+
+
+
+
+
+
Basic Tags
+
+ @description
+ @author
+ @version
+ @since
+
+
+
+
Parameters
+
+ @param
+ @returns
+ @throws
+ @example
+
+
+
+
Types & Classes
+
+ @typedef
+ @class
+ @method
+ @static
+
+
+
+
Advanced
+
+ @module
+ @callback
+ @interface
+ @link
+
+
)
-}
+}
\ No newline at end of file
diff --git a/app/parameters/page.tsx b/app/parameters/page.tsx
new file mode 100644
index 0000000..d7be16e
--- /dev/null
+++ b/app/parameters/page.tsx
@@ -0,0 +1,103 @@
+"use client"
+
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
+import { Badge } from "@/components/ui/badge"
+import { Separator } from "@/components/ui/separator"
+import { Code } from "lucide-react"
+import CodeHighlighter from "@/components/SyntaxHighlighter"
+import Sidebar from "@/components/Sidebar"
+import TableOfContents from "@/components/TableOfContents"
+import { jsdocData } from "@/lib/jsdoc-data"
+import Header from "@/components/Header"
+
+const parametersData = jsdocData.parameters
+
+export default function ParametersPage() {
+ // Generate TOC items from the data
+ const tocItems = parametersData.items.map((item, index) => ({
+ id: item.tag.replace("@", "").replace(/[^a-zA-Z0-9]/g, "-"),
+ title: item.tag,
+ level: 1
+ }))
+
+ return (
+
+
+
+
+
+
+
+ {/* Section Header */}
+
+
+ {parametersData.title}
+
+
+ {parametersData.description}
+
+
+
+ {/* Content Cards */}
+
+ {parametersData.items.map((item, index) => (
+
+
+
+
+
+ {item.tag}
+
+
+
+ {item.description}
+
+
+ {/* Syntax */}
+
+
Syntax:
+
+ {item.syntax}
+
+
+
+
+
+ {/* Example with Syntax Highlighting */}
+
+
Example:
+
+
+
+
+ ))}
+
+
+
+
+ {/* Footer */}
+
+
+ )
+}
diff --git a/app/type-definitions/page.tsx b/app/type-definitions/page.tsx
new file mode 100644
index 0000000..a38b9b6
--- /dev/null
+++ b/app/type-definitions/page.tsx
@@ -0,0 +1,102 @@
+"use client"
+
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
+import { Badge } from "@/components/ui/badge"
+import { Separator } from "@/components/ui/separator"
+import CodeHighlighter from "@/components/SyntaxHighlighter"
+import Sidebar from "@/components/Sidebar"
+import TableOfContents from "@/components/TableOfContents"
+import { jsdocData } from "@/lib/jsdoc-data"
+import Header from "@/components/Header"
+
+const typeDefinitionsData = jsdocData.types
+
+export default function TypeDefinitionsPage() {
+ // Generate TOC items from the data
+ const tocItems = typeDefinitionsData.items.map((item, index) => ({
+ id: item.tag.replace("@", "").replace(/[^a-zA-Z0-9]/g, "-"),
+ title: item.tag,
+ level: 1
+ }))
+
+ return (
+
+
+
+
+
+
+
+ {/* Section Header */}
+
+
+ {typeDefinitionsData.title}
+
+
+ {typeDefinitionsData.description}
+
+
+
+ {/* Content Cards */}
+
+ {typeDefinitionsData.items.map((item, index) => (
+
+
+
+
+
+ {item.tag}
+
+
+
+ {item.description}
+
+
+ {/* Syntax */}
+
+
Syntax:
+
+ {item.syntax}
+
+
+
+
+
+ {/* Example with Syntax Highlighting */}
+
+
Example:
+
+
+
+
+ ))}
+
+
+
+
+ {/* Footer */}
+
+
+ )
+}
diff --git a/components/Content.tsx b/components/Content.tsx
new file mode 100644
index 0000000..1a636ae
--- /dev/null
+++ b/components/Content.tsx
@@ -0,0 +1,139 @@
+'use client'
+
+import React from 'react'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
+import { Badge } from "@/components/ui/badge"
+import { Separator } from "@/components/ui/separator"
+import CustomSyntaxHighlighter from "@/components/SyntaxHighlighter"
+import { ExternalLink } from "lucide-react"
+
+interface Source {
+ name: string
+ url: string
+ description: string
+}
+
+interface JSDocItem {
+ tag: string
+ syntax: string
+ example: string
+ description: string
+ sources?: Source[]
+}
+
+interface JSDocSection {
+ title: string
+ description: string
+ items: JSDocItem[]
+}
+
+interface ContentProps {
+ activeSection: string
+ jsdocData: Record
+}
+
+export default function Content({ activeSection, jsdocData }: ContentProps) {
+ const currentSection = jsdocData[activeSection]
+
+ return (
+
+
+ {/* Kitchen Sink Example */}
+ {activeSection === 'kitchen-sink' && (
+
+
+
+
+ Kitchen Sink Example
+
+
+
+ A comprehensive example showcasing multiple JSDoc features in one code block
+
+
+
+
+
+
+ )}
+
+ {/* Section Header */}
+
+
+ {currentSection?.title || "Section"}
+
+
+ {currentSection?.description || "Documentation section"}
+
+
+
+ {/* Content Cards */}
+
+ {currentSection?.items.map((item, index) => (
+
+
+
+
+
+ {item.tag}
+
+
+
+ {item.description}
+
+
+ {/* Syntax */}
+
+
Syntax:
+
+ {item.syntax}
+
+
+
+
+
+ {/* Example with Syntax Highlighting */}
+
+
Example:
+
+
+
+ {/* Source Links */}
+ {item.sources && item.sources.length > 0 && (
+ <>
+
+
+
Sources & References:
+
+ {item.sources.map((source, sourceIndex) => (
+
+ ))}
+
+
+ )) || []}
+
+
+
(
+
+ {children}
+
+ )}
+ >
+ {code}
+
+
+
+ )
+}
+
+const sections = [
+ {
+ id: "kitchen-sink",
+ title: "Kitchen Sink Example",
+ icon: BookOpen,
+ subsections: ["Complete Example"],
+ },
+ {
+ id: "basic",
+ title: "Basic Tags",
+ icon: Tag,
+ subsections: ["@description", "@author", "@version", "@since", "@deprecated"],
+ },
+ {
+ id: "parameters",
+ title: "Parameters & Returns",
+ icon: Code,
+ subsections: ["@param", "@returns", "@throws", "@yields"],
+ },
+ {
+ id: "types",
+ title: "Type Definitions",
+ icon: Hash,
+ subsections: ["@typedef", "@property", "@enum", "@type"],
+ },
+ {
+ id: "functions",
+ title: "Functions & Classes",
+ icon: Settings,
+ subsections: ["@function", "@class", "@constructor", "@method", "@static", "@override"],
+ },
+ {
+ id: "modules",
+ title: "Modules & Namespaces",
+ icon: FileText,
+ subsections: ["@module", "@namespace", "@memberof", "@exports", "@requires"],
+ },
+ {
+ id: "advanced",
+ title: "Advanced Tags",
+ icon: BookOpen,
+ subsections: ["@callback", "@event", "@fires", "@listens", "@mixes", "@abstract"],
+ },
+ {
+ id: "objects",
+ title: "Objects & Interfaces",
+ icon: Hash,
+ subsections: ["@interface", "@implements", "@extends", "@mixin"],
+ },
+ {
+ id: "documentation",
+ title: "Documentation Tags",
+ icon: Info,
+ subsections: ["@example", "@see", "@link", "@tutorial", "@todo"],
+ },
+ {
+ id: "examples",
+ title: "Complete Examples",
+ icon: Info,
+ subsections: ["Function Example", "Class Example", "Module Example"],
+ },
+ {
+ id: "best-practices",
+ title: "Best Practices",
+ icon: Users,
+ subsections: ["Consistency", "Completeness", "Clarity", "Type Safety", "Examples"],
+ },
+]
+
+const jsdocData = {
+ kitchenSink: {
+ title: "Kitchen Sink Example",
+ description: "A comprehensive example showcasing multiple JSDoc features in one code block",
+ items: [
+ {
+ tag: "Complete Example",
+ syntax: "Complete function documentation",
+ example: `/**
+ * Advanced user management service with comprehensive JSDoc documentation
+ * @module UserService
+ * @description Handles user creation, authentication, and profile management
+ * @author Jane Smith
+ * @version 2.1.0
+ * @since 1.0.0
+ * @requires Database
+ * @requires EmailService
+ * @exports UserService
+ * @example
+ * // Initialize the service
+ * const userService = new UserService(database, emailService);
+ *
+ * // Create a new user
+ * const user = await userService.createUser({
+ * name: 'John Doe',
+ * email: 'john@example.com',
+ * role: 'admin'
+ * });
+ */
+
+/**
+ * @typedef {Object} UserData
+ * @property {string} name - Full name of the user
+ * @property {string} email - Email address (must be unique)
+ * @property {('admin'|'user'|'guest')} [role='user'] - User role in the system
+ * @property {number} [age] - User age (optional)
+ * @property {UserPreferences} [preferences] - User preferences object
+ */
+
+/**
+ * @typedef {Object} UserPreferences
+ * @property {boolean} emailNotifications - Whether to send email notifications
+ * @property {string} theme - UI theme preference
+ * @property {string} language - Preferred language code
+ */
+
+/**
+ * @callback ValidationCallback
+ * @param {Error|null} error - Validation error if any
+ * @param {boolean} isValid - Whether the data is valid
+ */
+
+/**
+ * User management service class
+ * @class UserService
+ * @implements {EventEmitter}
+ * @fires UserService#userCreated
+ * @fires UserService#userDeleted
+ * @example
+ * const service = new UserService(db, emailService);
+ * service.on('userCreated', (user) => {
+ * console.log('New user created:', user.name);
+ * });
+ */
+class UserService extends EventEmitter {
+ /**
+ * Creates a new UserService instance
+ * @constructor
+ * @param {Database} database - Database connection instance
+ * @param {EmailService} emailService - Email service for notifications
+ * @throws {TypeError} When database or emailService is not provided
+ * @since 1.0.0
+ */
+ constructor(database, emailService) {
+ super();
+ if (!database || !emailService) {
+ throw new TypeError('Database and EmailService are required');
+ }
+ this.db = database;
+ this.emailService = emailService;
+ }
+
+ /**
+ * Creates a new user in the system
+ * @async
+ * @method createUser
+ * @memberof UserService
+ * @param {UserData} userData - User information object
+ * @param {Object} [options={}] - Additional options
+ * @param {boolean} [options.sendWelcomeEmail=true] - Send welcome email
+ * @param {boolean} [options.validateEmail=true] - Validate email format
+ * @returns {Promise} Promise resolving to created user object
+ * @throws {ValidationError} When user data is invalid
+ * @throws {DuplicateEmailError} When email already exists
+ * @throws {DatabaseError} When database operation fails
+ * @fires UserService#userCreated
+ * @example
+ * // Basic user creation
+ * const user = await userService.createUser({
+ * name: 'Alice Johnson',
+ * email: 'alice@example.com'
+ * });
+ *
+ * @example
+ * // Advanced user creation with options
+ * const adminUser = await userService.createUser({
+ * name: 'Bob Admin',
+ * email: 'bob@example.com',
+ * role: 'admin',
+ * preferences: {
+ * emailNotifications: false,
+ * theme: 'dark',
+ * language: 'en'
+ * }
+ * }, {
+ * sendWelcomeEmail: false,
+ * validateEmail: true
+ * });
+ * @since 1.0.0
+ * @todo Add support for bulk user creation
+ * @todo Implement user avatar upload
+ */
+ async createUser(userData, options = {}) {
+ // Implementation here...
+
+ /**
+ * User created event
+ * @event UserService#userCreated
+ * @type {Object}
+ * @property {User} user - The created user object
+ * @property {Date} timestamp - When the user was created
+ */
+ this.emit('userCreated', { user: newUser, timestamp: new Date() });
+
+ return newUser;
+ }
+
+ /**
+ * Validates user email address
+ * @static
+ * @method validateEmail
+ * @param {string} email - Email address to validate
+ * @param {ValidationCallback} callback - Callback function for validation result
+ * @returns {boolean} True if email format is valid
+ * @example
+ * // Synchronous validation
+ * const isValid = UserService.validateEmail('test@example.com');
+ *
+ * // Asynchronous validation with callback
+ * UserService.validateEmail('test@example.com', (error, isValid) => {
+ * if (error) {
+ * console.error('Validation error:', error);
+ * } else {
+ * console.log('Email is valid:', isValid);
+ * }
+ * });
+ * @since 1.2.0
+ */
+ static validateEmail(email, callback) {
+ // Implementation here...
+ }
+
+ /**
+ * @deprecated Since version 2.0.0. Use {@link UserService#createUser} instead.
+ * @method addUser
+ * @param {UserData} userData - User data
+ * @returns {Promise} Created user
+ * @see {@link UserService#createUser}
+ */
+ async addUser(userData) {
+ console.warn('addUser is deprecated. Use createUser instead.');
+ return this.createUser(userData);
+ }
+}
+
+/**
+ * @namespace UserService.Utils
+ * @description Utility functions for user management
+ */
+UserService.Utils = {
+ /**
+ * Formats user display name
+ * @function formatDisplayName
+ * @memberof UserService.Utils
+ * @param {string} firstName - User's first name
+ * @param {string} lastName - User's last name
+ * @returns {string} Formatted display name
+ * @example
+ * const displayName = UserService.Utils.formatDisplayName('John', 'Doe');
+ * console.log(displayName); // "John D."
+ */
+ formatDisplayName(firstName, lastName) {
+ return \`\${firstName} \${lastName.charAt(0)}.\`;
+ }
+};
+
+module.exports = UserService;`,
+ description: "Complete function documentation with all common tags",
+ },
+ ],
+ },
+ basic: {
+ title: "Basic Tags",
+ description: "Essential JSDoc tags for documenting your code",
+ items: [
+ {
+ tag: "@description",
+ syntax: "@description {string} Description text",
+ example:
+ "/**\n * @description Calculates the sum of two numbers\n * @param {number} a - First number\n * @param {number} b - Second number\n * @returns {number} The sum\n */\nfunction add(a, b) {\n return a + b;\n}",
+ description: "Provides a description of the function, class, or variable",
+ },
+ {
+ tag: "@author",
+ syntax: "@author {string} Author name ",
+ example: "/**\n * @author John Doe \n * @author Jane Smith \n */",
+ description: "Specifies the author(s) of the code",
+ },
+ {
+ tag: "@version",
+ syntax: "@version {string} Version number",
+ example: "/**\n * @version 1.2.0\n * @since 1.0.0\n */",
+ description: "Indicates the current version of the code",
+ },
+ {
+ tag: "@since",
+ syntax: "@since {string} Version when added",
+ example: "/**\n * @since 1.0.0\n * @description Added in the initial release\n */",
+ description: "Specifies when the feature was first added",
+ },
+ {
+ tag: "@deprecated",
+ syntax: "@deprecated {string} Deprecation message",
+ example:
+ "/**\n * @deprecated Since version 2.0.0. Use newFunction() instead.\n * @see {@link newFunction}\n */\nfunction oldFunction() {\n // deprecated implementation\n}",
+ description: "Marks code as deprecated with migration guidance",
+ },
+ ],
+ },
+ parameters: {
+ title: "Parameters & Returns",
+ description: "Document function parameters, return values, and exceptions",
+ items: [
+ {
+ tag: "@param",
+ syntax: "@param {type} name Description",
+ example:
+ "/**\n * @param {number} x - The first number\n * @param {number} y - The second number\n * @param {Object} [options] - Optional configuration\n * @param {boolean} [options.strict=false] - Use strict mode\n */\nfunction calculate(x, y, options = {}) {\n // implementation\n}",
+ description: "Documents function parameters with types and descriptions",
+ },
+ {
+ tag: "@returns",
+ syntax: "@returns {type} Description",
+ example:
+ "/**\n * @param {number[]} numbers - Array of numbers\n * @returns {number} The sum of all numbers\n * @returns {null} Returns null if array is empty\n */\nfunction sum(numbers) {\n if (numbers.length === 0) return null;\n return numbers.reduce((a, b) => a + b, 0);\n}",
+ description: "Documents the return value and its type",
+ },
+ {
+ tag: "@throws",
+ syntax: "@throws {ErrorType} Description",
+ example:
+ "/**\n * @param {string} email - User email address\n * @throws {TypeError} When email is not a string\n * @throws {Error} When email format is invalid\n */\nfunction validateEmail(email) {\n if (typeof email !== 'string') {\n throw new TypeError('Email must be a string');\n }\n if (!email.includes('@')) {\n throw new Error('Invalid email format');\n }\n}",
+ description: "Documents exceptions that may be thrown",
+ },
+ {
+ tag: "@yields",
+ syntax: "@yields {type} Description",
+ example:
+ "/**\n * @generator\n * @yields {number} The next number in the Fibonacci sequence\n * @returns {Generator}\n */\nfunction* fibonacci() {\n let a = 0, b = 1;\n while (true) {\n yield a;\n [a, b] = [b, a + b];\n }\n}",
+ description: "Documents what a generator function yields",
+ },
+ ],
+ },
+ types: {
+ title: "Type Definitions",
+ description: "Define and document custom types and interfaces",
+ items: [
+ {
+ tag: "@typedef",
+ syntax: "@typedef {Object} TypeName",
+ example: "/**\n * @typedef {Object} User\n * @property {string} name\n * @property {number} age\n */",
+ description: "Defines a custom type",
+ },
+ {
+ tag: "@property",
+ syntax: "@property {type} name Description",
+ example: "/**\n * @property {string} email - User email address\n */",
+ description: "Documents object properties",
+ },
+ {
+ tag: "@enum",
+ syntax: "@enum {type}",
+ example: '/**\n * @enum {string}\n */\nconst Status = {\n PENDING: "pending",\n COMPLETE: "complete"\n}',
+ description: "Documents enumeration values",
+ },
+ {
+ tag: "@type",
+ syntax: "@type {type}",
+ example: "/**\n * @type {string|number}\n */\nlet value;",
+ description: "Specifies the type of a variable",
+ },
+ ],
+ },
+ functions: {
+ title: "Functions & Classes",
+ description: "Document functions, classes, constructors, and methods",
+ items: [
+ {
+ tag: "@function",
+ syntax: "@function",
+ example: "/**\n * @function calculateTotal\n * @description Calculates order total\n */",
+ description: "Explicitly marks something as a function",
+ },
+ {
+ tag: "@class",
+ syntax: "@class",
+ example: "/**\n * @class\n * @description Represents a user account\n */",
+ description: "Documents a class",
+ },
+ {
+ tag: "@constructor",
+ syntax: "@constructor",
+ example: "/**\n * @constructor\n * @param {string} name - User name\n */",
+ description: "Documents a constructor function",
+ },
+ {
+ tag: "@method",
+ syntax: "@method",
+ example: "/**\n * @method getName\n * @returns {string} The user name\n */",
+ description: "Documents a method",
+ },
+ {
+ tag: "@static",
+ syntax: "@static",
+ example: "/**\n * @static\n * @method createUser\n */",
+ description: "Indicates a static method or property",
+ },
+ {
+ tag: "@override",
+ syntax: "@override",
+ example: "/**\n * @override\n * @method toString\n */",
+ description: "Indicates method overrides parent method",
+ },
+ ],
+ },
+ modules: {
+ title: "Modules & Namespaces",
+ description: "Organize code with modules, namespaces, and membership",
+ items: [
+ {
+ tag: "@module",
+ syntax: "@module ModuleName",
+ example: "/**\n * @module UserUtils\n * @description Utilities for user management\n */",
+ description: "Documents a module",
+ },
+ {
+ tag: "@namespace",
+ syntax: "@namespace NamespaceName",
+ example: "/**\n * @namespace MyApp.Utils\n */",
+ description: "Documents a namespace",
+ },
+ {
+ tag: "@memberof",
+ syntax: "@memberof ParentName",
+ example: "/**\n * @memberof MyApp.Utils\n * @function formatName\n */",
+ description: "Indicates membership in a parent",
+ },
+ {
+ tag: "@exports",
+ syntax: "@exports ModuleName",
+ example: "/**\n * @exports UserService\n */",
+ description: "Documents what a module exports",
+ },
+ {
+ tag: "@requires",
+ syntax: "@requires ModuleName",
+ example: "/**\n * @requires lodash\n */",
+ description: "Documents module dependencies",
+ },
+ ],
+ },
+ advanced: {
+ title: "Advanced Tags",
+ description: "Advanced JSDoc features for complex documentation needs",
+ items: [
+ {
+ tag: "@callback",
+ syntax: "@callback CallbackName",
+ example: "/**\n * @callback RequestCallback\n * @param {Error} error\n * @param {Object} response\n */",
+ description: "Documents a callback function type",
+ },
+ {
+ tag: "@event",
+ syntax: "@event EventName",
+ example: "/**\n * @event MyClass#dataLoaded\n * @type {Object}\n */",
+ description: "Documents an event",
+ },
+ {
+ tag: "@fires",
+ syntax: "@fires EventName",
+ example: "/**\n * @fires MyClass#dataLoaded\n */",
+ description: "Indicates function fires an event",
+ },
+ {
+ tag: "@listens",
+ syntax: "@listens EventName",
+ example: "/**\n * @listens MyClass#dataLoaded\n */",
+ description: "Indicates function listens to an event",
+ },
+ {
+ tag: "@mixes",
+ syntax: "@mixes MixinName",
+ example: "/**\n * @mixes EventEmitter\n */",
+ description: "Documents that class mixes in another",
+ },
+ {
+ tag: "@abstract",
+ syntax: "@abstract",
+ example: "/**\n * @abstract\n * @method process\n */",
+ description: "Indicates abstract method or class",
+ },
+ ],
+ },
+ examples: {
+ title: "Complete Examples",
+ description: "Real-world JSDoc documentation examples",
+ items: [
+ {
+ tag: "Function Example",
+ syntax: "Complete function documentation",
+ example: `/**
+ * Calculates the area of a rectangle
+ * @function calculateArea
+ * @param {number} width - The width of the rectangle
+ * @param {number} height - The height of the rectangle
+ * @returns {number} The area of the rectangle
+ * @throws {TypeError} When width or height is not a number
+ * @example
+ * // Calculate area of 5x3 rectangle
+ * const area = calculateArea(5, 3);
+ * console.log(area); // 15
+ * @since 1.0.0
+ * @author Jane Smith
+ */
+function calculateArea(width, height) {
+ if (typeof width !== 'number' || typeof height !== 'number') {
+ throw new TypeError('Width and height must be numbers');
+ }
+ return width * height;
+}`,
+ description: "Complete function documentation with all common tags",
+ },
+ {
+ tag: "Class Example",
+ syntax: "Complete class documentation",
+ example: `/**
+ * Represents a user in the system
+ * @class User
+ * @param {string} name - The user's name
+ * @param {string} email - The user's email address
+ * @example
+ * const user = new User('John Doe', 'john@example.com');
+ * console.log(user.getName()); // 'John Doe'
+ */
+class User {
+ /**
+ * Create a user
+ * @constructor
+ * @param {string} name - The user's name
+ * @param {string} email - The user's email address
+ */
+ constructor(name, email) {
+ this.name = name;
+ this.email = email;
+ }
+
+ /**
+ * Get the user's name
+ * @method getName
+ * @returns {string} The user's name
+ */
+ getName() {
+ return this.name;
+ }
+}`,
+ description: "Complete class documentation with constructor and methods",
+ },
+ {
+ tag: "Module Example",
+ syntax: "Complete module documentation",
+ example: `/**
+ * User management module
+ * @module UserManagement
+ * @description Handles user creation and deletion
+ * @requires Database
+ * @requires EmailService
+ * @exports createUser
+ * @exports deleteUser
+ * @example
+ * // Create a user
+ * const user = createUser('John Doe', 'john@example.com');
+ * console.log(user);
+ *
+ * // Delete a user
+ * deleteUser(user.id);
+ */
+const Database = require('./Database');
+const EmailService = require('./EmailService');
+
+function createUser(name, email) {
+ // Implementation here
+}
+
+function deleteUser(userId) {
+ // Implementation here
+}
+
+module.exports = {
+ createUser,
+ deleteUser
+};`,
+ description: "Complete module documentation with dependencies and exports",
+ },
+ ],
+ },
+ "best-practices": {
+ title: "Best Practices",
+ description: "Guidelines for writing effective JSDoc documentation",
+ items: [
+ {
+ tag: "Consistency",
+ syntax: "Use consistent formatting and style",
+ example:
+ "// Always use the same format for similar tags\n// Good: @param {string} name - User name\n// Good: @param {number} age - User age",
+ description: "Maintain consistent formatting across your documentation",
+ },
+ {
+ tag: "Completeness",
+ syntax: "Document all public APIs",
+ example: "// Document all parameters, return values, and exceptions\n// Include examples for complex functions",
+ description: "Ensure all public functions, classes, and modules are documented",
+ },
+ {
+ tag: "Clarity",
+ syntax: "Write clear, concise descriptions",
+ example: "// Good: Calculates user age from birth date\n// Bad: Does age stuff",
+ description: "Use clear, descriptive language that explains purpose and behavior",
+ },
+ {
+ tag: "Type Safety",
+ syntax: "Always specify types for parameters and returns",
+ example:
+ "// Always include types\n@param {string|null} name - User name or null\n@returns {Promise} Promise resolving to user object",
+ description: "Include detailed type information to improve code reliability",
+ },
+ {
+ tag: "Examples",
+ syntax: "Include usage examples for complex functions",
+ example:
+ "/**\n * @example\n * // Basic usage\n * const result = myFunction('input');\n * \n * @example\n * // Advanced usage\n * const result = myFunction('input', { option: true });\n */",
+ description: "Provide practical examples showing how to use the code",
+ },
+ ],
+ },
+ objects: {
+ title: "Objects & Interfaces",
+ description: "Document object structures, interfaces, and inheritance",
+ items: [
+ {
+ tag: "@interface",
+ syntax: "@interface InterfaceName",
+ example: "/**\n * @interface Drawable\n * @description Interface for drawable objects\n */",
+ description: "Documents an interface that classes can implement",
+ },
+ {
+ tag: "@implements",
+ syntax: "@implements {InterfaceName}",
+ example: "/**\n * @class Circle\n * @implements {Drawable}\n */",
+ description: "Indicates that a class implements an interface",
+ },
+ {
+ tag: "@extends",
+ syntax: "@extends ParentClass",
+ example: "/**\n * @class ColoredCircle\n * @extends Circle\n */",
+ description: "Documents class inheritance",
+ },
+ {
+ tag: "@mixin",
+ syntax: "@mixin MixinName",
+ example: "/**\n * @mixin EventEmitter\n * @description Adds event handling capabilities\n */",
+ description: "Documents a mixin that can be mixed into classes",
+ },
+ ],
+ },
+ documentation: {
+ title: "Documentation Tags",
+ description: "Tags for linking, examples, and additional documentation",
+ items: [
+ {
+ tag: "@example",
+ syntax: "@example\n// Example code here",
+ example:
+ "/**\n * @example\n * // Basic usage\n * const result = myFunction('test');\n * console.log(result);\n */",
+ description: "Provides usage examples",
+ },
+ {
+ tag: "@see",
+ syntax: "@see {reference}",
+ example: "/**\n * @see {@link MyClass#method}\n * @see https://example.com/docs\n */",
+ description: "References related documentation or code",
+ },
+ {
+ tag: "@link",
+ syntax: "{@link reference}",
+ example: "/**\n * Uses {@link MyClass} for processing\n */",
+ description: "Creates inline links to other documentation",
+ },
+ {
+ tag: "@tutorial",
+ syntax: "@tutorial TutorialName",
+ example: "/**\n * @tutorial getting-started\n */",
+ description: "Links to a tutorial document",
+ },
+ {
+ tag: "@todo",
+ syntax: "@todo Description of what needs to be done",
+ example: "/**\n * @todo Add input validation\n * @todo Optimize performance\n */",
+ description: "Documents future improvements or fixes needed",
+ },
+ ],
+ },
+}
+
+export default function JSDocCheatsheet() {
+ const [activeSection, setActiveSection] = useState("kitchen-sink")
+ const [expandedSections, setExpandedSections] = useState(["kitchen-sink"])
+ const [isScrolling, setIsScrolling] = useState(false)
+
+ const toggleSection = (sectionId: string) => {
+ setExpandedSections((prev) =>
+ prev.includes(sectionId) ? prev.filter((id) => id !== sectionId) : [...prev, sectionId],
+ )
+ }
+
+ const scrollToTag = (tag: string) => {
+ const element = document.getElementById(tag.replace("@", "").replace(/[^a-zA-Z0-9]/g, "-"))
+ if (element) {
+ setIsScrolling(true)
+ element.scrollIntoView({ behavior: "smooth", block: "start" })
+
+ // Reset scrolling state after animation
+ setTimeout(() => setIsScrolling(false), 1000)
+
+ // Highlight the element briefly
+ element.classList.add("ring-2", "ring-primary", "ring-opacity-50")
+ setTimeout(() => {
+ element.classList.remove("ring-2", "ring-primary", "ring-opacity-50")
+ }, 2000)
+ }
+ }
+
+ useEffect(() => {
+ const handleScroll = () => {
+ if (isScrolling) return // Don't update during programmatic scrolling
+
+ const sections = Object.keys(jsdocData)
+ const scrollPosition = window.scrollY + 200
+
+ for (const sectionId of sections) {
+ const element = document.getElementById(`section-${sectionId}`)
+ if (element) {
+ const { offsetTop, offsetHeight } = element
+ if (scrollPosition >= offsetTop && scrollPosition < offsetTop + offsetHeight) {
+ setActiveSection(sectionId)
+ break
+ }
+ }
+ }
+ }
+
+ window.addEventListener("scroll", handleScroll)
+ return () => window.removeEventListener("scroll", handleScroll)
+ }, [isScrolling])
+
+ return (
+
+ {/* Header */}
+
+
+
+
JSDoc Cheatsheet
+
Complete Reference for JavaScript Documentation
+
+
+
+
+
+ {/* Sidebar Navigation */}
+
+
+ {/* Main Content */}
+
+
+ {/* Kitchen Sink Example */}
+
+
+
+
+ Kitchen Sink Example
+
+
+
+ A comprehensive example showcasing multiple JSDoc features in one code block
+
+
+
+
+
+
+
+ {/* Section Header */}
+
+
+ {jsdocData[activeSection as keyof typeof jsdocData]?.title || "Section"}
+
+
+ {jsdocData[activeSection as keyof typeof jsdocData]?.description || "Documentation section"}
+
+
+
+ {/* Content Cards */}
+
+ {jsdocData[activeSection as keyof typeof jsdocData]?.items.map((item, index) => (
+
+
+
+
+
+ {item.tag}
+
+
+
+ {item.description}
+
+
+ {/* Syntax */}
+
+
Syntax:
+
+ {item.syntax}
+
+
+
+
+
+ {/* Example with Syntax Highlighting */}
+
+
Example:
+
+
+
+
+ )) || []}
+
+
+
+
+
+ {/* Footer */}
+
+