Code Documentation Samples

/**
 * Calculates the factorial of a non-negative integer.
 *
 * @param {number} n - The non-negative integer to calculate factorial for
 * @returns {number} The factorial of n
 * @throws {RangeError} If n is negative or not an integer
 * @example
 * factorial(5) // returns 120
 * factorial(0) // returns 1
 */
function factorial(n) {
  if (!Number.isInteger(n) || n < 0) {
    throw new RangeError('n must be a non-negative integer');
  }
  if (n === 0 || n === 1) {
    return 1;
  }
  return n * factorial(n - 1);
}

/**
 * Formats a date into a human-readable string.
 *
 * @param {Date} date - The date object to format
 * @param {string} [format="ISO"] - The format style: "ISO", "US", or "EU"
 * @param {boolean} [includeTime=true] - Whether to include time in the output
 * @returns {string} The formatted date string
 * @example
 * formatDate(new Date(), "US", false) // returns "12/25/2024"
 */
function formatDate(date, format = 'ISO', includeTime = true) {
  const options = {
    year: 'numeric',
    month: format === 'US' ? 'numeric' : '2-digit',
    day: '2-digit',
    hour: includeTime ? '2-digit' : undefined,
    minute: includeTime ? '2-digit' : undefined
  };
  return date.toLocaleDateString(format === 'US' ? 'en-US' : 'en-GB', options);
}

/**
 * Represents a user account with authentication capabilities.
 *
 * @class User
 * @example
 * const user = new User('[email protected]', 'password123');
 * await user.authenticate();
 */
class User {
  /**
   * Creates an instance of User.
   *
   * @param {string} email - The user's email address
   * @param {string} password - The user's password (will be hashed)
   */
  constructor(email, password) {
    /**
     * @type {string}
     * @readonly
     */
    this.email = email;
    /**
     * @type {string}
     * @private
     */
    this._passwordHash = this._hashPassword(password);
    /**
     * @type {Date}
     */
    this.createdAt = new Date();
  }

  /**
   * Hashes a password using SHA-256.
   *
   * @private
   * @param {string} password - The plain text password
   * @returns {string} The hashed password
   */
  _hashPassword(password) {
    // Implementation simplified for example
    return 'hashed_' + password;
  }

  /**
   * Authenticates the user with the provided credentials.
   *
   * @async
   * @param {string} password - The password to verify
   * @returns {Promise<boolean>} True if authentication successful
   * @throws {AuthenticationError} If authentication fails
   */
  async authenticate(password) {
    const hash = this._hashPassword(password);
    return hash === this._passwordHash;
  }

  /**
   * Updates the user's email address.
   *
   * @param {string} newEmail - The new email address
   * @throws {ValidationError} If email is invalid
   */
  updateEmail(newEmail) {
    if (!this._isValidEmail(newEmail)) {
      throw new Error('Invalid email format');
    }
    this.email = newEmail;
  }
}

/**
 * Represents the configuration options for an API client.
 *
 * @interface ApiClientConfig
 */
interface ApiClientConfig {
  /**
   * The base URL for all API requests.
   *
   * @type {string}
   * @example "https://api.example.com"
   */
  baseUrl: string;

  /**
   * Authentication token for API requests.
   *
   * @type {string}
   * @optional
   */
  authToken?: string;

  /**
   * Request timeout in milliseconds.
   *
   * @type {number}
   * @default 5000
   */
  timeout?: number;

  /**
   * Number of retry attempts for failed requests.
   *
   * @type {number}
   * @default 3
   */
  retries?: number;

  /**
   * Enable debug logging.
   *
   * @type {boolean}
   * @default false
   */
  debug?: boolean;
}

/**
 * Response data structure from the API.
 *
 * @interface ApiResponse
 * @template T - The type of data returned
 */
interface ApiResponse<T> {
  /**
   * HTTP status code.
   *
   * @type {number}
   */
  status: number;

  /**
   * Response message.
   *
   * @type {string}
   */
  message: string;

  /**
   * The payload data.
   *
   * @type {T}
   */
  data: T;
}

/**
 * Generic stack implementation with type safety.
 *
 * @template T - The type of elements in the stack
 * @example
 * const stack = new Stack<number>();
 * stack.push(1);
 * stack.push(2);
 * console.log(stack.pop()); // 2
 */
class Stack<T> {
  private items: T[] = [];

  /**
   * Creates an empty stack.
   */
  constructor() {}

  /**
   * Adds an element to the top of the stack.
   *
   * @param {T} item - The element to add
   * @returns {void}
   * @example
   * stack.push('item');
   */
  push(item: T): void {
    this.items.push(item);
  }

  /**
   * Removes and returns the top element from the stack.
   *
   * @returns {T | undefined} The removed element, or undefined if stack is empty
   * @throws {Error} If the stack is empty
   * @example
   * const item = stack.pop();
   */
  pop(): T | undefined {
    if (this.isEmpty()) {
      throw new Error('Stack is empty');
    }
    return this.items.pop();
  }

  /**
   * Returns the top element without removing it.
   *
   * @returns {T | undefined} The top element, or undefined if stack is empty
   * @example
   * const top = stack.peek();
   */
  peek(): T | undefined {
    return this.items[this.items.length - 1];
  }

  /**
   * Checks if the stack is empty.
   *
   * @returns {boolean} True if stack is empty, false otherwise
   */
  isEmpty(): boolean {
    return this.items.length === 0;
  }

  /**
   * Returns the number of elements in the stack.
   *
   * @returns {number} The size of the stack
   */
  size(): number {
    return this.items.length;
  }
}

def calculate_bmi(weight: float, height: float) -> float:
    """Calculate Body Mass Index (BMI).

    BMI is a measure of body fat based on height and weight.
    Formula: weight (kg) / height (m)^2

    Args:
        weight: Weight in kilograms. Must be positive.
        height: Height in meters. Must be positive.

    Returns:
        The BMI value as a float.

    Raises:
        ValueError: If weight or height is not positive.

    Examples:
        >>> calculate_bmi(70, 1.75)
        22.857...
        >>> calculate_bmi(80, 1.80)
        24.691...
    """
    if weight <= 0 or height <= 0:
        raise ValueError("Weight and height must be positive")

    return weight / (height ** 2)


def format_name(first: str, last: str, middle: str = "") -> str:
    """Format a full name from given parts.

    Args:
        first: First name
        last: Last name
        middle: Middle name (optional)

    Returns:
        Formatted full name

    Examples:
        >>> format_name("John", "Doe")
        'John Doe'
        >>> format_name("Jane", "Smith", "Marie")
        'Jane Marie Smith'
    """
    parts = [first, middle, last] if middle else [first, last]
    return " ".join(parts)

class BankAccount:
    """A simple bank account class.

    This class provides basic banking operations including deposits,
    withdrawals, and balance inquiries.

    Attributes:
        account_number (str): Unique account identifier
        balance (float): Current account balance
        owner (str): Name of the account owner

    Examples:
        >>> account = BankAccount("12345", "John Doe")
        >>> account.deposit(100)
        >>> account.get_balance()
        100.0
    """

    def __init__(self, account_number: str, owner: str, initial_balance: float = 0):
        """Initialize a new bank account.

        Args:
            account_number: Unique account identifier
            owner: Name of the account owner
            initial_balance: Starting balance (default: 0)

        Raises:
            ValueError: If initial_balance is negative
        """
        self.account_number = account_number
        self.owner = owner
        self.balance = initial_balance

    def deposit(self, amount: float) -> bool:
        """Deposit money into the account.

        Args:
            amount: Amount to deposit (must be positive)

        Returns:
            True if deposit successful

        Raises:
            ValueError: If amount is not positive
        """
        if amount <= 0:
            raise ValueError("Deposit amount must be positive")
        self.balance += amount
        return True

    def withdraw(self, amount: float) -> bool:
        """Withdraw money from the account.

        Args:
            amount: Amount to withdraw (must be positive)

        Returns:
            True if withdrawal successful

        Raises:
            ValueError: If amount is invalid or insufficient funds
        """
        if amount <= 0:
            raise ValueError("Withdrawal amount must be positive")
        if amount > self.balance:
            raise ValueError("Insufficient funds")
        self.balance -= amount
        return True

    def get_balance(self) -> float:
        """Get the current account balance.

        Returns:
            Current balance as a float
        """
        return self.balance

import java.util.HashMap;
import java.util.Map;
import java.util.Objects;

/**
 * Represents a simplified HTTP response with status, headers, and body.
 *
 * <p>This class encapsulates the components of an HTTP response and provides
 * methods to access and modify them.
 *
 * @author Elysia Tools
 * @version 1.0
 * @since 1.0
 *
 * @see HttpClient
 * @see HttpRequest
 */
public class HttpResponse {

  /** The HTTP status code (e.g., 200, 404, 500) */
  private int statusCode;

  /** The response body content */
  private String body;

  /** Response headers as key-value pairs */
  private Map<String, String> headers;

  /**
   * Constructs a new HttpResponse with the specified status code.
   *
   * @param statusCode the HTTP status code (must be between 100 and 599)
   * @throws IllegalArgumentException if statusCode is invalid
   */
  public HttpResponse(int statusCode) {
    setStatusCode(statusCode);
    this.body = "";
    this.headers = new HashMap<>();
  }

  /**
   * Constructs a new HttpResponse with status code and body.
   *
   * @param statusCode the HTTP status code
   * @param body the response body content
   */
  public HttpResponse(int statusCode, String body) {
    this(statusCode);
    this.body = body;
  }

  /**
   * Gets the HTTP status code.
   *
   * @return the status code
   */
  public int getStatusCode() {
    return statusCode;
  }

  /**
   * Sets the HTTP status code.
   *
   * @param statusCode the new status code (100-599)
   * @throws IllegalArgumentException if status code is out of range
   */
  public void setStatusCode(int statusCode) {
    if (statusCode < 100 || statusCode > 599) {
      throw new IllegalArgumentException("Invalid status code: " + statusCode);
    }
    this.statusCode = statusCode;
  }

  /**
   * Gets the response body.
   *
   * @return the body content, or empty string if not set
   */
  public String getBody() {
    return body;
  }

  /**
   * Sets the response body.
   *
   * @param body the new body content (can be null, will be converted to empty string)
   */
  public void setBody(String body) {
    this.body = Objects.toStringElse(body, "");
  }

  /**
   * Checks if the response indicates success (status code 2xx).
   *
   * @return true if status code is between 200 and 299
   */
  public boolean isSuccess() {
    return statusCode >= 200 && statusCode < 300;
  }
} 

/**
 * Validates and formats a phone number according to international standards.
 *
 * <p>This method accepts a phone number in various formats and returns
 * a standardized E.164 format. It handles country codes, area codes, and
 * validates the number structure.
 *
 * @param phoneNumber the phone number to validate and format
 *        (can include spaces, dashes, parentheses)
 * @param countryCode the ISO 3166-1 alpha-2 country code
 *        (e.g., "US", "GB", "FR")
 *
 * @return the formatted phone number in E.164 format
 *         (e.g., "+14155552671")
 *
 * @throws IllegalArgumentException if {@code phoneNumber} is null or empty
 * @throws IllegalArgumentException if {@code countryCode} is not a valid ISO code
 * @throws NumberFormatException if the phone number contains invalid characters
 *
 * @see <a href="https://en.wikipedia.org/wiki/E.164">E.164 Specification</a>
 *
 * @since 1.0
 *
 * @deprecated Use {@link PhoneNumberUtil#parse(String, String)} instead
 */
@Deprecated
public static String formatPhoneNumber(String phoneNumber, String countryCode) {
  // Implementation details...
  return null;
}

/**
 * Calculates the compound interest over a given period.
 *
 * <p>Formula: A = P(1 + r/n)^(nt)<br>
 * Where A = final amount, P = principal, r = annual rate,<br>
 * n = times compounded per year, t = years
 *
 * @param principal the initial investment amount (must be positive)
 * @param annualRate the annual interest rate as decimal (e.g., 0.05 for 5%)
 * @param timesPerYear number of times interest is compounded per year
 * @param years the investment period in years
 *
 * @return the final amount including compound interest
 *
 * @throws IllegalArgumentException if any parameter is invalid
 *
 * @see Math#pow(double, double)
 */
public static double calculateCompoundInterest(
  double principal,
  double annualRate,
  int timesPerYear,
  int years) {
  // Implementation details...
  return 0.0;
} 

/**
 * Advanced data processor with transformation and validation capabilities.
 *
 * @template TInput - Input data type
 * @template TOutput - Output data type
 *
 * @example
 * const processor = new DataProcessor<string, number>({
 *   transform: (str) => parseInt(str),
 *   validate: (num) => !isNaN(num)
 * });
 */
class DataProcessor<TInput, TOutput> {
  /**
   * Processing options configuration.
   *
   * @typedef {Object} ProcessorOptions
   * @property {Function} transform - Transform function
   * @property {Function} validate - Validation function
   * @property {boolean} [async=false] - Enable async processing
   * @property {number} [maxRetries=3] - Maximum retry attempts
   */
  private options: ProcessorOptions;

  /**
   * Creates a new data processor instance.
   *
   * @param {ProcessorOptions} options - Configuration options
   * @throws {TypeError} If options is invalid
   */
  constructor(options: ProcessorOptions) {
    this.options = options;
  }

  /**
   * Processes input data through transformation and validation.
   *
   * @async
   * @param {TInput} data - Input data to process
   * @param {Object} [context] - Optional processing context
   * @param {string} [context.traceId] - Trace ID for logging
   * @returns {Promise<TOutput>} Processed output data
   * @throws {ValidationError} If validation fails
   * @throws {ProcessingError} If transformation fails
   *
   * @example
   * const result = await processor.process("123", { traceId: "abc123" });
   */
  async process(data: TInput, context?: { traceId?: string }): Promise<TOutput> {
    // Implementation...
    return {} as TOutput;
  }
} 

/**
 * Binary search implementation for sorted arrays.
 *
 * <p>This method performs a binary search on a sorted array to find
 * the index of a target value. Binary search has O(log n) time complexity.
 *
 * <h3>Algorithm Steps:</h3>
 * <ol>
 *   <li>Initialize low = 0, high = array length - 1</li>
 *   <li>While low <= high:
 *     <ul>
 *       <li>Calculate mid = low + (high - low) / 2</li>
 *       <li>If array[mid] == target, return mid</li>
 *       <li>If array[mid] < target, low = mid + 1</li>
 *       <li>Else, high = mid - 1</li>
 *     </ul>
 *   </li>
 *   <li>If not found, return -1</li>
 * </ol>
 *
 * <h3>Usage Examples:</h3>
 * <pre><code>
 * // Basic usage
 * const arr = [1, 3, 5, 7, 9, 11];
 * binarySearch(arr, 7);  // returns 3
 *
 * // Element not found
 * binarySearch(arr, 4);  // returns -1
 *
 * // Empty array
 * binarySearch([], 5);   // returns -1
 * </code></pre>
 *
 * @param {number[]} array - The sorted array to search (must be sorted ascending)
 * @param {number} target - The value to find
 * @returns {number} The index of the target, or -1 if not found
 *
 * @throws {TypeError} If array is not an array or contains non-numeric values
 *
 * @see {@link https://en.wikipedia.org/wiki/Binary_search_algorithm|Binary Search on Wikipedia}
 * @see {@link linearSearch} for unsorted arrays
 *
 * @example
 * // Find index of value 5
 * const index = binarySearch([1, 2, 3, 4, 5], 5);
 * console.log(index); // Output: 4
 *
 * @author Elysia Development Team
 * @version 1.2.0
 * @since 1.0.0
 * @readonly
 */
function binarySearch(array: number[], target: number): number {
  if (!Array.isArray(array) || array.some(item => typeof item !== 'number')) {
    throw new TypeError('First argument must be an array of numbers');
  }

  let low = 0;
  let high = array.length - 1;

  while (low <= high) {
    const mid = Math.floor(low + (high - low) / 2);

    if (array[mid] === target) {
      return mid;
    }

    if (array[mid] < target) {
      low = mid + 1;
    } else {
      high = mid - 1;
    }
  }

  return -1;
}