[Python-Dev] Documenting types outside of typing

[Barry Warsaw]

In his review of PR#4911, Antoine points to the documentation of two type definitions in importlib.resources, Package and Resource.

https://github.com/python/cpython/pull/4911/files#diff-2a479c407f7177f3d7cb876f244e47bcR804

One question is what markup to use for type definitions.  I’m using class:: because that’s what’s used in typing and there doesn’t seem to be any better alternative.

More to the point, Antoine questions whether these two types should be documented at all:

https://github.com/python/cpython/pull/4911#discussion_r158801065

"What I mean is that a class is supposed to specify concrete behaviour, but being a type, Package doesn't have any methods or attributes of its own. So I don't see the point of mentioning it in the docs.”

I suggest that they are worth documenting because they help to organize the discussion about what API is expected from the arguments to the functions, without having to duplicate that information in every function description.  I also think that since you’ll see those types in the code, they are worth documenting.  I don’t think you *lose* anything by including their documentation.

But Antoine makes a good point that we probably don’t have a lot of precedence here, so suggests we discuss it on python-dev to come up with some useful conventions.  I haven’t kept up on the dataclasses discussion, but given that types are important in that API too, have the same issues come up there and if so, how are they being handled?

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/20171227/6cb02f1f/attachment.sig>