Writing Good Docstrings

Quell extracts requirements from your docstrings. Better docstrings = more verified tests.

The Raises section is the most important

Quell reads Raises entries as direct requirements. Write them precisely:

def process_payment(amount: float, currency: str) -> dict:
    """
    Process a payment.

    Raises:
        ValueError: If amount is zero or negative.
        ValueError: If currency is not a supported 3-letter code.
        PermissionError: If the current user doesn't have payment privileges.
    """

Each Raises entry becomes a test requirement. Quell will generate a test that verifies the exception is raised under the described condition.

Be specific about conditions

Vague: ValueError: If amount is invalid.

Good: ValueError: If amount is zero or negative.

The more specific the condition, the better the generated test.

Document return constraints

def get_user_age(user_id: int) -> int:
    """
    Get the age of a user.

    Returns:
        int: User's age. Always >= 0 and <= 150.

    Raises:
        KeyError: If user_id does not exist.
    """

Use type annotations alongside docstrings

Quell combines type annotations with docstring requirements:

from typing import Optional

def find_user(email: str) -> Optional[User]:
    """
    Find a user by email.

    Returns None if no user with the given email exists.
    The email must be a valid format (contains '@').

    Raises:
        ValueError: If email is empty or does not contain '@'.
    """

Quell will generate tests for both the Raises condition and the Optional return.

Pydantic models are read automatically

You don't need extra docstrings for Pydantic — field constraints are read directly:

class Payment(BaseModel):
    amount: float = Field(gt=0, description="Payment amount, must be positive")
    currency: str = Field(min_length=3, max_length=3)
    user_id: int = Field(ge=1)

Quell generates tests for gt=0, min_length=3, max_length=3, and ge=1 constraints automatically.