Description
We have two main bodies of documentation right now:
- PEP 484 serves to some extent as reference documentation on the type system. The PEP format isn't directly oriented to this purpose, as it also has the history of the proposal, the rejected alternatives, etc. It's also to some extent a historical document and has a high barrier to making changes, which impedes incrementally improving it as documentation. At present PEP 484 also leaves a lot of details unspecified, because we're reluctant to standardize details that we haven't gotten enough experience with in real usage to be confident how they should work.
- The Mypy documentation is aimed at being user documentation for the type system, as well as on the use of the
mypytype-checker tool. It describes the system in more narrative fashion aimed at someone writing type annotations, and it describes details that aren't specified in the PEP. This is much like how for most Python language features, developers generally refer to the Python Language Reference rather than a corresponding PEP.
We've arrived at this setup through a particular historical path, and there are some things that aren't great about it. As we continue to improve the documentation, we should work out what set of bodies of documentation we'd like to have, and how to move toward that.
Here's one setup that I think would improve some things:
- PEP 484, in much the same role as today.
- User-facing documentation of the PEP 484 type system and annotation syntax. Perhaps under a title like "Python Type Hints Reference", to follow the title of PEP 484 "Type Hints".
- Documentation of the use of the
mypytool itself. This would focus on the CLI and the workflow specific to the type-checker, plus any Mypy-specific details that are too involved to put into a "Mypy only" box in the Type Hints Reference. (The latter might then have a box that mostly just links to the relevant section of this document.) Perhaps the "Mypy Usage Reference"? A quick-start or tutorial section might have some small annotation examples in order to be self-contained for its purpose, but the bulk of the work of documenting how to write annotations would be left to the Type Hints Reference, which this would just link to.
A good first draft of the Python Type Hints Reference and Mypy Usage Reference might come from just taking the existing Mypy documentation and pulling it apart into two documents. Most of it would land in the Type Hints Reference, I think, and the Mypy Usage Reference would be relatively short.
The big value of making this distinction, though, comes if we can make the Python Type Hints Reference function as shared documentation across all the tools that implement PEP 484, including PyCharm and pytype, with the same kind of shared status as the PEP itself -- playing a role complementary to the PEP by addressing annotation-writers rather than implementors, having a more narrative style with more examples, and being readily editable with a low-friction pull-request workflow to continuously improve as exposition.
In particular:
- To the extent that the various tools that implement PEP 484 agree on details, this allows us all to share the effort of documenting them well, and allows our users (especially users of multiple tools!) to go to a common place to read about them.
- To the extent those agreed-on details aren't specified in the PEP, we should consider making them explicit there in any case. Or when the implementations happen to agree but we aren't yet confident of standardizing that for some reason, it'd be good to be explicit that that's the case where we do document those details.
- To the extent the implementations disagree, this is likely to cause grief to users who use multiple tools (e.g., Need a standard for searching stub files typing#184), and we should be discussing those details to find agreement (as we are in that thread) and putting that in the PEP.
- To the extent that the implementations disagree and we can't work out the differences, or haven't yet, users will benefit from explicitly documenting the disagreements. In a Type Hints Reference we might do this with boxes labeled "Mypy only:" and so on, like how the Library Reference documents differences between Python versions.