[Python-Dev] Documenting types outside of typing

[Ivan Levkivskyi]

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#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
>
>
> _______________________________________________
> 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>