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

examples/example_python.py

@@ -0,0 +1,114 @@
+"""Example Python module for Doc2Man demonstration.
+
+This module contains various function types to demonstrate
+the docstring parsing capabilities of Doc2Man.
+"""
+
+
+def greet(name: str, greeting: str = "Hello") -> str:
+    """Greet a person with a custom greeting message.
+
+    Args:
+        name: The name of the person to greet. Should be a non-empty string.
+        greeting: The greeting word to use. Defaults to "Hello".
+
+    Returns:
+        A formatted greeting string like "Hello, John!".
+
+    Raises:
+        ValueError: If name is empty or None.
+
+    Examples:
+        >>> greet("Alice")
+        'Hello, Alice!'
+        >>> greet("Bob", "Hi")
+        'Hi, Bob!'
+    """
+    if not name:
+        raise ValueError("Name cannot be empty")
+    return f"{greeting}, {name}!"
+
+
+def calculate_sum(numbers: list[float]) -> dict[str, float]:
+    """Calculate the sum and average of a list of numbers.
+
+    Args:
+        numbers: A list of numeric values. Must not be empty.
+
+    Returns:
+        A dictionary containing:
+        - sum: The total sum of all numbers
+        - average: The arithmetic mean
+        - count: The number of elements
+
+    Raises:
+        ValueError: If the input list is empty.
+
+    Examples:
+        >>> calculate_sum([1, 2, 3, 4, 5])
+        {'sum': 15, 'average': 3.0, 'count': 5}
+    """
+    if not numbers:
+        raise ValueError("Input list cannot be empty")
+
+    total = sum(numbers)
+    count = len(numbers)
+
+    return {
+        "sum": total,
+        "average": total / count if count > 0 else 0,
+        "count": count
+    }
+
+
+class FileHandler:
+    """A class for handling file operations.
+
+    This class provides methods for reading, writing,
+    and processing files with proper error handling.
+
+    Attributes:
+        filepath: The path to the file being handled.
+    """
+
+    def __init__(self, filepath: str):
+        """Initialize the FileHandler with a file path.
+
+        Args:
+            filepath: Path to the file to handle.
+        """
+        self.filepath = filepath
+
+    def read(self, encoding: str = "utf-8") -> str:
+        """Read the entire content of the file.
+
+        Args:
+            encoding: The text encoding to use. Defaults to UTF-8.
+
+        Returns:
+            The file contents as a string.
+
+        Raises:
+            FileNotFoundError: If the file doesn't exist.
+            UnicodeDecodeError: If the file cannot be decoded.
+
+        Examples:
+            >>> handler = FileHandler("example.txt")
+            >>> content = handler.read()
+        """
+        with open(self.filepath, "r", encoding=encoding) as f:
+            return f.read()
+
+    def write(self, content: str, encoding: str = "utf-8") -> None:
+        """Write content to the file.
+
+        Args:
+            content: The text content to write.
+            encoding: The text encoding to use. Defaults to UTF-8.
+
+        Examples:
+            >>> handler = FileHandler("output.txt")
+            >>> handler.write("Hello, World!")
+        """
+        with open(self.filepath, "w", encoding=encoding) as f:
+            f.write(content)