<div dir="ltr"><div><div><div><div>FWIW the same problem was discussed a year ago when documenting typing. At that time the discussion was not conclusive,<br></div>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<br></div>PEP 560 many types in typing will stop being class objects, and will be just (compact) objects. Therefore, my understanding is that<br></div>all special forms like Union, Any, ClassVar, etc. will use data:: in the docs.<br></div><div><br></div><div>Concerning the question whether it makes to document types, I think it makes sense if it is a publicly available type (or type alias)</div><div>that will be useful to annotate user code.<br></div><div><br>--<br></div>Ivan<br><br><br></div><div class="gmail_extra"><br><div class="gmail_quote">On 27 December 2017 at 17:41, Barry Warsaw <span dir="ltr"><<a href="mailto:barry@python.org" target="_blank">barry@python.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">In his review of PR#4911, Antoine points to the documentation of two type definitions in importlib.resources, Package and Resource.<br>
<br>
<a href="https://github.com/python/cpython/pull/4911/files#diff-2a479c407f7177f3d7cb876f244e47bcR804" rel="noreferrer" target="_blank">https://github.com/python/<wbr>cpython/pull/4911/files#diff-<wbr>2a479c407f7177f3d7cb876f244e47<wbr>bcR804</a><br>
<br>
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.<br>
<br>
More to the point, Antoine questions whether these two types should be documented at all:<br>
<br>
<a href="https://github.com/python/cpython/pull/4911#discussion_r158801065" rel="noreferrer" target="_blank">https://github.com/python/<wbr>cpython/pull/4911#discussion_<wbr>r158801065</a><br>
<br>
"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.”<br>
<br>
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.<br>
<br>
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?<br>
<br>
Cheers,<br>
-Barry<br>
<br>
<br>______________________________<wbr>_________________<br>
Python-Dev mailing list<br>
<a href="mailto:Python-Dev@python.org">Python-Dev@python.org</a><br>
<a href="https://mail.python.org/mailman/listinfo/python-dev" rel="noreferrer" target="_blank">https://mail.python.org/<wbr>mailman/listinfo/python-dev</a><br>
Unsubscribe: <a href="https://mail.python.org/mailman/options/python-dev/levkivskyi%40gmail.com" rel="noreferrer" target="_blank">https://mail.python.org/<wbr>mailman/options/python-dev/<wbr>levkivskyi%40gmail.com</a><br>
<br></blockquote></div><br></div>