There’s an issue with docstrings standards like Google-style and Numpydoc-style: parsing them is pretty fragile, because they are not specific enough. They actually don’t even have a specification at all: both have a style guide (Google-style, Numpydoc-style) but no specs, so it’s up to each tool to guess and decide how they should be parsed. In Griffe, the ambiguous aspects are configurable with options, like whether to allow blank lines in Numpydoc-style sections. I recently had to make the Google-style parser more strict (blank line required before section, no blank line allowed after section title) because it had false-positives. None of this is officially specified.
These two styles, Google and Numpydoc, also have divergent features and designs: the Google-style seems to use/recommend Markdown, while Numpydoc is based on rST and designed only to work within Sphinx. Numpydoc supports “See also” section that should be parsed a certain way, while the Google-style does not. Numpydoc requires types to be added to Returns sections, forcing user to duplicate what’s already in the signature. Numpydoc supports multiple named items for Returns sections, while the Google-style does not. Many things are up to interpretation, and make it hard to elaborate a common ground of features and data structures to store the information.
There’s also what I call the Sphinx-style (not sure it has even a name), using
:param foo: Hello. to describe parameters for example. This style does not support most of the sections supported by Numpydoc and the Google-style: no yields, no receives, no warns, no kwargs. It also seems to be based on / tied to rST. Not that rST is a problem, but a style/standard that is tied to a particular markup cannot IMO be reliably used by different tooling. The only truly markup-agnostic style that I know of is the Google-style, and that’s one of the reason I use it myself.
With type annotations in signatures, types are not required in docstrings anymore. It means that a pure docstring parser won’t provide all the necessary information to its consumers. It has to also run static/dynamic analysis to obtain types and default values from signatures (for example), or to put this responsibility on the consumer. It means tooling must constantly merge two sources of information: structured data obtained from static/dynamic analysis, and structured data obtained from parsing docstrings, and it’s sometimes hard to do right.
For these reasons, I like what PEP 727 proposes. It structures the information in the code itself (in annotations) so that we don’t have to design, write or parse custom syntaxes in docstrings. Docstrings can then use plain markup, chosen by maintainers (Markdown, AsciiDoc, etc.), in a consistent manner. If it is accepted, and later gets extended to support other kinds of information, it will also standardize what kind of information can be added to code, which I think is very important.
The PEP has one limitation I would like to mention: structuring information in the code won’t allow to intertwine prose and sections in docstrings anymore (like parameters, then text, then exceptions, then text again, then returns section), though it was never really specified either, and could be alleviated by tooling, for example with placeholders in docstrings that get replaced with rendered information.
I won’t comment on the verbosity aspects as I think the PEP addresses it, but will add that documentation generators can very well strip annotations of the surrounding
Annotated when rendering docs. The data is there to collect, and can be hidden when exposed to users. Next version of mkdocstrings will do just that (I tried, it works)