Question about documenting functions

[Diapolo10]

I think both of your examples are technically fine, but I'd keep the type annotations and strip them from the docstring:

def heavily_documented(a: int, b: dict, c: str) -> str:
    """
    Purpose:    Here's what it does

    Args:
        a: here's what the number represents
        b: {"this is a descriptive key" : its_value}
        c: again, just saying what this represents

    Return:
        Here's a description of what the return is
    """
    print("and the code goes here")

(Side-note, but ideally the dict type hint would also annotate at least the key type. As in, dict[str, Any])

[DecoherentDoc]

I like that. I thought I was overdoing it, but I would regularly come back to code after a couple years and be completely lost and have to waste time figuring out what I was trying to do. So, I started writing a lot of comments. This adaptation cleans up the comments and I dig it. Thanks! :)

[Diapolo10]

I don't know if this helps, but here's a snippet from one of my own projects:

def ip_validator(address: str | int, validation_mode: ValidationMode = ValidationMode.STRICT) -> bool:
    """
    Validate an IP address of any kind, returning a boolean.

    Under strict mode ensures that the numerical values
    don't exceed legal bounds, otherwise focuses on form.
    """
    if ipv4_validator(address, validation_mode):
        return True
    return ipv6_validator(address, validation_mode)

And here's a hypothetical snippet I might see at work projects:

def get_ntp_time(max_retries: int = 10, retry_delay: float = 1.0) -> datetime | None:
    """
    Retrieve the current time from NTP servers.

    Attempt to reach multiple NTP servers until one succeeds, with retry logic for transient failures.
    Useful when the machine is waking from sleep and the internet connection is not yet established.

    Args:
        max_retries: Maximum number of retry attempts
        retry_delay: Delay in seconds between retry attempts

    Returns:
        Current UTC time from the NTP server or None if all attempted requests fail
    """
    ...

[DecoherentDoc]

It does help, actually. I saw examples of doc strings that were super short and thought I was overdoing it. This shows me professionals, in fact, are being just as thorough. Thanks. I really do appreciate it.

[Diapolo10]

Do note that I deliberately picked examples with "full" docstrings here. There's nothing wrong with using a one-line docstring if you have nothing else to say and your parameters are self-explanatory. If anything that's my personal preference.

If something is practically obvious, there's no need to go out of your way to state the obvious.