JSDoc Cheatsheet

/**
 * Advanced user management service with comprehensive JSDoc documentation
 * @module UserService
 * @description Handles user creation, authentication, and profile management
 * @author Jane Smith <jane@example.com>
 * @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<User>} 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<User>} 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;