bug: Google docstrings: no support for non-multiple or non-named values in Yields section about griffe

[pawamoy]

Hey again @the-13th-letter, thanks for the great report. I agree with the suggestion to make yields and returns consistent. Maybe also receives?

[the-13th-letter]

Hey again @the-13th-letter, thanks for the great report. I agree with the suggestion to make yields and returns consistent.

:)

Maybe also receives?

I thought about that as well, but I don't have a good case for this. Just a couple of disjointed random thoughts.

• Google's style guide doesn't talk about generator input via generator.send(...) at all. So it's anyone's guess how to properly format this or even talk about this in a valid Google-style Python program.

• The Receives block comes from numpydoc. So it's much more important that it is compatible with NumPy's style than with Google's style. numpydoc currently (v1.8.0rc0) says: “Since, like for Yields and Returns, a single object is always passed to the method, this may describe either the single parameter, or positional arguments passed as a tuple.” So there may be some desire for receives_multiple_items = False.

  • The function analog to Receives is (positional-only) Args/Parameters. I cannot really imagine anyone seriously suggesting that the Args/Parameters block should support not accepting multiple parameters. Why would Receives be any different? So maybe there's no desire receives_multiple_items = False.

• I find the need for receives_named_value = False somewhat unlikely: you generally do spam, eggs, *parrots = yield ... inside the generator, so you already have “parameter names” (spam, eggs, *parrots) that you probably want to use in the Receives block.

  • But then, perhaps it's a spam = yield ... case where spam is an internal name that you don't want to expose, and now the docs are forcing you to name things anyway...

So yeah, I don't really know what to do with Receives. And I don't think I'm the right person to ask about that either, because I use neither Receives nor the NumPy docstring format in general.

[pawamoy]

Thanks for your thoughts.

So yeah, I don't really know what to do with Receives. And I don't think I'm the right person to ask about that either, because I use neither Receives nor the NumPy docstring format in general.

Then I'd vote we make "Receives" consistent with the rest, for the sake of consistency. Both Google-style and Numpydoc-style are underspecified, so I always allowed myself some wiggle-room with the goal of making both styles more similar, structurally speaking.