python-docstring-generator

What this skill does

• Adds docstrings to all Python functions and methods
• Ensures all functions with parameters have proper parameter documentation with type information
• Documents return values with Returns: sections
• Handles async functions, classes, and utility functions
• Maintains existing docstring style conventions in codebase (Google, NumPy, or Sphinx)
• Follows PEP 257 standards for Python code documentation
• Integrates with Python's type hints for better IDE support

When to use

Use this when:

• Implementing new functions, classes, or utility modules in Python projects
• Refactoring code and adding missing documentation
• Preparing for code review and ensuring proper docstring standards
• Functions lack docstrings or have incomplete parameter documentation
• You need to enforce docstring presence as part of quality checks

Common signals:

• Python functions without docstrings
• Functions with parameters but missing parameter documentation
• Return values not documented
• Async functions without proper return type documentation
• Python code lacking type-aware documentation

Python Docstring Standard Formats

Google Style (Recommended for most projects)

Basic Function

def calculate_sum(a: int, b: int) -> int:
    """Calculate the sum of two numbers.

    Args:
        a: The first number to add.
        b: The second number to add.

    Returns:
        The sum of a and b.
    """
    return a + b

Async Function

async def fetch_user(user_id: str) -> User:
    """Fetch user data from API.

    Args:
        user_id: The unique identifier of user.

    Returns:
        The user data object.

    Raises:
        APIError: When the API request fails.
    """
    response = await fetch(f"/api/users/{user_id}")
    if not response.ok:
        raise APIError('Failed to fetch user')
    return response.json()

Class Method

class UserProfile:
    """User profile display component.

    This class manages user profile data and display logic.

    Attributes:
        user_id: The user's unique identifier.
        on_edit: Callback when edit button is clicked.
    """

    def __init__(self, user_id: str, on_edit: Callable):
        """Initialize user profile.

        Args:
            user_id: The user's unique identifier.
            on_edit: Callback when edit button is clicked.
        """
        self.user_id = user_id
        self.on_edit = on_edit