PEP 727: Documentation Metadata in Typing

PEPs
182

:cry:

Quick, personal summary, with new thoughts:

  • Counter-argument: “it’s not typing”. Annotated was designed to annotate types, true, but also says:

    As such, Annotated can be useful for code that wants to use annotations for purposes outside Python’s static typing system.

    Unfortunately the typing module is the only meaningful location in the standard library for Doc (next to Annotated). There isn’t a generic documentation-related standard module :confused: (maybe we could create one :smiling_imp:?). Even if many do not use or consider typing primarily as documentation, it is still also documentation.

  • Counter-argument: “it’s too verbose”. Not really. Spacing taken aside, you can alias Annotated as A, then A[int, Doc("string")] is ~10 characters more than int, for each documented parameter. But from that we could substract the average length of parameter names, since we don’t have to repeat them in function/class docstrings.

  • Counter-argument: “it makes big signatures”. Big signatures can be collapsed (partly or completely) with adequate tooling. Even without Doc, signatures with annotated types can grow quite big, so it would make sense to me that IDEs and text editors would allow collapsing each parameter in signatures, maybe just showing the (truncated) unannotated type and (truncated) default value.

  • Counter-argument: “it’s not pretty or as pretty as function docstrings”. Personal preference :person_shrugging:

  • Counter-argument: “accepting it in the stdlib puts pressure on the ecosystem to adopt it”. Recent thought I had: True, but the opposite is true too. By not providing a standard way to structure docs data, pressure is put on the ecosystem to rely on non-standard, divergent, unspecified and sub-optimal docstring styles.

Anyway, I hope I’m not starting a debate over again :sweat_smile: I’m actually happy if Doc lives in a third-party library :slightly_smiling_face: Just wanted to share my perspective again as someone who works a lot with docstring styles (and grows to enjoy them less and less). I hope we can continue working and discussing towards a standard solution even after this PEP is withdrawn or rejected :smiling_face:

2 Likes