PEP 727: Documentation Metadata in Typing

[blhsing (Ben Hsing)]

@mikeshardmind

Even if this was worth pursuing, and I don’t think it is, @ was used in that hypothetical because there is no conceivable future to need matmul for types. Using - is problematic due to the potential for difference types in the future (ie. Iterable[str] - str, being any iterable of strings that isn’t just a string), paired with strings being used for forward references in typing.

Good point, so type - 'string' is problematic because 'string' can be used as a forward reference of a type, but I think type -- 'string' can still work because - 'string' can be made a Doc('string'), which type.__sub__ can special-case and make Annotated[type, Doc('string')].

Keep in mind that there were plenty of other things brought up in this discussion against this idea that don’t matter what the syntax actually would be.

Yes, the syntax just occurred to me and I thought I’d share it here just in case the other arguments against this idea get resolved later.

EDIT: Actually, I think I may have just resolved what I believe to be the biggest argument against this idea, namely that the original proposal makes the annotation too verbose, to the point that it adversely affects readability.

So instead of:

def some_function(
    some_parameter: Annotated[SomeType, Doc("Some documentation goes here")],
    **kwargs: Annotated[Any, Doc("Additional keyword arguments")]
) -> Annotated[SomeReturn, Doc("Some details about this return type")]:
    """ Documenting the function itself here """

It can now be:

def some_function(
    some_parameter: SomeType -- "Some documentation goes here",
    **kwargs: Any -- "Additional keyword arguments"
) -> SomeReturn -- "Some details about this return type":
    """ Documenting the function itself here """

which looks a lot less verbose and more readable to me.

Perhaps it’s enough to nudge this proposal back on track for a reconsideration?