PEP 727: Documentation Metadata in Typing

PEPs
50

Some alternate proposals which could inform a final design of this PEP:

I think this has been suggested years before, but not as a topic I could find: having a new Doc annotation:

def fn(
    x: Doc[int, "Documentation here"],
    y: Doc[Annotated[int, Custom()], "More docs"],
) -> Doc[int, "Returned thing"]:
    """Function docstring."""
    return x + y

Note this PEP would work on return types as well.

Going full Sphinx (and I think PyCharm already supports this), the strong literal after the symbol:

def fn(
    x: int,
    """Documentation here."""

    y: Annotated[int, Custom()],
    """More docs."""

) -> int:
    """Function docstring.

    Returns:
        Returned thing
    """"

    return x + y

Outside of alternatives, there are cases where the docstring just sucks for parameter (and return-value) documentation. People on this thread against a more structured approach to this are really (but likely unintentionally) saying “your problem isn’t worth making easier to solve, Python will never have an easy and reliable way to solve it”.

Perhaps there is a way to sell this functionality as a tool for specific scenarios, and certainly not the blessed way in the majority of cases.

Also nit, technically this is purely annotations, not typing (especially as one of the two main problems is extraction at runtime) :slight_smile: .

I think I will create a package today implementing the initial proposal (unless someone else already has), which I suggested earlier. This can be used to get better telemetry.

Edit: done: docannometa

1 Like