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

Ivan Levkivskyi levkivskyi at gmail.com
Wed Dec 27 18:59:01 EST 2017

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.

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.

-- Ivan

On 27 December 2017 at 17:41, Barry Warsaw <barry at python.org> wrote:

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#discussionr158801065 "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

Python-Dev mailing list Python-Dev at python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/ levkivskyi%40gmail.com -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.python.org/pipermail/python-dev/attachments/20171228/89c2bd18/attachment.html>

More information about the Python-Dev mailing list