Add templates and example files for Python, Go, and JavaScript

examples/example_javascript.js

@@ -0,0 +1,126 @@
+/**
+ * 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
+};