Support multiple return variable docments

[gorkamunoz]

This may be an enhancement, if it does not yet exist. Is it possible to have multiple return variable with their own description? This means, for instance, a function that outputs 2 different variables, for which I want to give details separately. My current solution involves stacking the description of all outputs in the details of the single return row as shown here:

def foo2(# input 1
         a:int = 5, 
         # input 2
         b:int = 5, 
         # first output: a+b
         # second output: a-b
        )-> int|int: 
    
    '''
    Test multiple outputs
   '''
    return a+b, a-b

which leads to the following table:

Is it possible to have a similar disposition as with inputs, where the name of the output or maybe just the details are shown for every output separately? I was digging into the numpy docstring documentation and couldn't find a way of doing this with that either.

Thanks!!

[seeM]

Thanks for the issue write-up! The first one is definitely a bug, we'll track that in the corresponding nbdev issue you created.

For the second, do you perhaps have a way that you envision docments for multiple return values working? How would the syntax look, and how would the output table look? And would that be much of an improvement over the current behaviour?

[gorkamunoz]

Hi! Thanks for the update. I have edited the Issue to only contain the improvement.

For the output table, it was thinking something like this:

This allows to better explain each of the outputs. In the case of more complex functions, the resulting table is somewhat messy. You can see it in this example, where I have to purposely put dashes to differentiate outputs.

For the input sintax, I am really not sure what would be the solution. In numpy docstrings I would write it as (it does not work there neither):

Returns
--------
out_1 : int
  sum of input 1 and 2
out_2 : int
  difference between input 1 and 2