0

I have the function

def foo(bar):
    return bar(var1, var2)

where bar is a function that takes two variables named var1 and var2 and returns an str obj, what is the proper numpydocs way to document this?

I thought of something like:

def foo(bar):
    """
    ...
    Parameters
    -----------
    bar: func(var1: list[str], var2: str) -> str
    """
    return bar(var1, var2)
Tomergt45
  • 579
  • 1
  • 7
  • 19
  • `scipy.optimize` (and iterpolate) has a lot of functions that take a function as their first argument (e.g. `minimize`). (and sometimes other parameters, like the jacobian are callables as well). – hpaulj Aug 23 '20 at 17:37

1 Answers1

1

I'd do this way:

def foo(bar):
    """
    ...
    Parameters
    ----------
    bar: callable
        - ``var1``: description of parameter var1 (`list`).
        - ``var2``: description of parameter var2 (`str`).
    """
    return bar(var1, var2)

If you definitely need to include the return type of that internal function, then maybe:


def foo(bar):
    """
    ...
    Parameters
    ----------
    bar: callable

         ``bar(var1: list[str], var2: str) -> str``

    Some description about `var1` and `var2`.
    """
    return bar(var1, var2)
Péter Leéh
  • 2,069
  • 2
  • 10
  • 23
  • What about the return value? – Tomergt45 Aug 23 '20 at 17:14
  • @Tomergt45 Why would you want to document the return value of `bar` inside another function? That's what `bar`'s docstring is for. `foo` returns that anyways. Also, why don't you let the user decide what is `var1` and `var2`? In most cases you should include it in `foo`'s signature, rather than leaving it internally. – Péter Leéh Aug 23 '20 at 17:27
  • Based on a different parameter the expected return value differs in my case. And regardless I can’t only see value from documenting the return value of bar, because for example in a lot of cases bar isn’t a function but a lambda function, so it doesn’t have a doc to explain itself – Tomergt45 Aug 23 '20 at 17:34
  • @Tomergt45 What's the point in documenting `bar`'s return value, then document the exact same thing again now with `foo`'s return value in the same docstring? – Péter Leéh Aug 23 '20 at 17:39
  • I think I confused you with my example, this is a simplified version but in my real problem, foo doesn’t return the output of bar but instead executes some operations on the return value – Tomergt45 Aug 23 '20 at 17:43