[Python-Dev] Documenting types outside of typing (original) (raw)

Barry Warsaw barry at python.org
Thu Dec 28 10:14:05 EST 2017

On Dec 27, 2017, at 18:59, Ivan Levkivskyi <levkivskyi at gmail.com> wrote:

FWIW the same problem was discussed a year ago when documenting typing. At that time the discussion was not conclusive, so that some types use class:: directive while other use data:: directive. At that time Guido was in favour of data:: and now in view of PEP 560 many types in typing will stop being class objects, and will be just (compact) objects. Therefore, my understanding is that all special forms like Union, Any, ClassVar, etc. will use data:: in the docs.

Thanks. I see that typing.rst has been updated to use data:: so I’ll change my branch accordingly.

Concerning the question whether it makes to document types, I think it makes sense if it is a publicly available type (or type alias) that will be useful to annotate user code.

Thanks, that’s my feeling about it too.

Cheers, -Barry

-------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 833 bytes Desc: Message signed with OpenPGP URL: <http://mail.python.org/pipermail/python-dev/attachments/20171228/9437b791/attachment.sig>

More information about the Python-Dev mailing list