0

Suppose I have two functions:

def func_a(x, passed_parameter):
    """
    Return ...
    
    Args:
        x: ...
        passed_parameter: Do a specific thing.
    """
    ...
    
def func_b(passed_parameter):
    """
    Return ...
    
    Args:
        passed_parameter: Do a specific thing.
    """
    ...

I think it is clear enough that this situation arises in programming, and copy-pasting is not an option for obvious reasons. My question then is, specifically for pdoc (Google-style docstrings), how do I document passed_parameter in func_a. My first thought is just writing

passed_parameter: See `func_b`.

This is fine, but I was wondering if there is a more preferred way of doing this either in pdoc, or a recommended way in a PEP. I tried something like "See func_b.passed_parameter" but this does not hyperlink to the parameter in pdoc.

Kraigolas
  • 5,121
  • 3
  • 12
  • 37
  • 1
    The fact that `passed_parameter` is passed (and only passed) to `func_b` is somewhat of an implementation detail. I would simply document what effect `passed_parameter` has on the effect of `func_a`. – chepner Dec 11 '21 at 18:36
  • On the other hand, maybe it should not be documented at all. `def func_a(x, **kwargs)` or `def func_a(x, **args)`, with a simple note that additional arguments are passed directly to `func_b` (if `func_a`'s dependency on `func_b` is something you want to document). (Or that any argument that `func_b` accepts are also accepted by `func_a`.) – chepner Dec 11 '21 at 18:37
  • 1
    Unless "all other" arguments are passed to `func_b` making `func_a` more like a wrapper then I would use @chepner's suggestion that you document the effect that the parameter has on `func_a`. particularly if there is a 3rd parameter in `func_a` passed to `func_c`. – JonSG Dec 11 '21 at 18:44

0 Answers0