Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Additional support for numpy returns section with no annotation, or just type annotation #173

Closed
machow opened this issue Jun 26, 2023 · 1 comment

Comments

@machow
Copy link
Contributor

machow commented Jun 26, 2023

Describe the bug

For a numpy returns section, it seems like there may be some small issues with two cases:

  • when there is no name or type annotation specified (the annotation becomes ":")
  • when there is only an annotation (the annotation starts with ": ")

Here's a docstring with comments trying to explain the two cases:

        Returns
        -------
        list of int
            A list of integers.
        flag : bool
            Some kind
            of flag.
        x :
            Name only

        # new case ----
        # worked in a previous version of griffe. For functions with a single returns, this is
        # useful for having the return value be the functions return type hint
        :
            No name or annotation

        # new case ----
        # it looked like this may have included ": " in the annotation
        : int
            Only annotation

I can start a PR in a second, and definitely am happy to make any tweaks / changes! I realize the spec for the Returns section is a bit ambiguous, but the "no name or annotation" case seems particularly useful for just documenting the return type hint (maybe an issue similar in spirit to this one!: #137)

@pawamoy
Copy link
Member

pawamoy commented Jun 27, 2023

Yeah, the Numpydoc spec comes short on these cases. It doesn't take into account that devs might annotate types in the signature and not in the docstring. I'm OK with supporting these additional cases. We should reach out to the style spec maintainers at some point. UPDATE: done: numpy/numpydoc#463

# for free to join this conversation on GitHub. Already have an account? # to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants