/**
 * Example JavaScript module for Doc2Man demonstration.
 * This module contains various function types to demonstrate
 * JSDoc parsing capabilities.
 */

/**
 * Says hello to a person.
 *
 * @param {string} name - The name of the person to greet
 * @param {string} [greeting="Hello"] - The greeting word to use
 * @returns {string} A formatted greeting string
 * @throws {TypeError} If name is not a string
 *
 * @example
 * greet("Alice")
 * // returns "Hello, Alice!"
 *
 * @example
 * greet("Bob", "Hi")
 * // returns "Hi, Bob!"
 */
function greet(name, greeting = "Hello") {
    if (typeof name !== "string") {
        throw new TypeError("Name must be a string");
    }
    return `${greeting}, ${name}!`;
}

/**
 * Calculates statistics for an array of numbers.
 *
 * @param {number[]} numbers - Array of numbers to analyze
 * @returns {Object} Object containing sum, average, and count
 * @property {number} sum - Total sum of all numbers
 * @property {number} average - Arithmetic mean
 * @property {number} count - Number of elements
 *
 * @example
 * calculateStats([1, 2, 3, 4, 5])
 * // returns { sum: 15, average: 3, count: 5 }
 */
function calculateStats(numbers) {
    const sum = numbers.reduce((a, b) => a + b, 0);
    const count = numbers.length;
    return {
        sum,
        average: count > 0 ? sum / count : 0,
        count
    };
}

/**
 * A class for handling file operations.
 * Provides methods for reading and writing files.
 */
class FileHandler {
    /**
     * Create a new FileHandler.
     * @param {string} filepath - Path to the file
     */
    constructor(filepath) {
        this.filepath = filepath;
    }

    /**
     * Read the file contents.
     * @returns {string} File contents as string
     * @throws {Error} If file doesn't exist
     *
     * @example
     * const handler = new FileHandler("data.txt");
     * const content = handler.read();
     */
    read() {
        return "File content here";
    }

    /**
     * Write content to the file.
     * @param {string} content - Content to write
     * @returns {void}
     *
     * @example
     * const handler = new FileHandler("output.txt");
     * handler.write("Hello, World!");
     */
    write(content) {
        console.log(`Writing to ${this.filepath}: ${content}`);
    }
}

/**
 * Asynchronous function to fetch data from URL.
 *
 * @param {string} url - The URL to fetch
 * @returns {Promise<Object>} Promise resolving to response data
 *
 * @example
 * fetchData("https://api.example.com/data")
 *   .then(data => console.log(data));
 */
async function fetchData(url) {
    return { url, status: "ok" };
}

/**
 * Arrow function for processing items.
 *
 * @param {Array} items - Items to process
 * @param {Function} callback - Function to apply to each item
 * @returns {Array} Processed items
 *
 * @example
 * const doubled = processItems([1, 2, 3], x => x * 2);
 * // returns [2, 4, 6]
 */
const processItems = (items, callback) => items.map(callback);

module.exports = {
    greet,
    calculateStats,
    FileHandler,
    fetchData,
    processItems
};