<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Mon, Jan 19, 2015 at 10:39 PM, Terry Reedy <span dir="ltr"><<a href="mailto:tjreedy@udel.edu" target="_blank">tjreedy@udel.edu</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">On 1/19/2015 2:54 PM, Guido van Rossum wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Unfortunately PEP 257 falls short on specifying how to describe<br>
arguments -- it has only one example, it's not normative, and there's<br>
not much code that follows the example. The reST conventions are more<br>
common, but the stdlib itself rarely uses them.<br>
</blockquote>
<br></span>
Because I have not seen such used, except maybe once, I have been meaning to ask if I am allowed to use rst markup in stdlib docstrings?<span class=""><br></span></blockquote><div><br></div><div>I prefer you don't use them. We don't generate docs from the stdlib sources, and if someone generated them locally they would probably be doing themselves a disservice -- the docstrings exist for the benefit of the help() builtin, which AFAIK doesn't understand rst markup.<br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">
> It would be nice to come<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
up with a better convention that takes PEP 484 into account (so doc<br>
generators can incorporate the argument type annotations into the<br>
generated output, merged with per-argument from the docstring).<br>
</blockquote>
<br></span>
My impression is that the plan is that stdlib .py files would not have type annotations, but that they might be in stub files.  Still true?<br></blockquote><div><br></div><div>Correct. The stdlib is a special flower in so many ways... (Stubs are also useful for 3rd party libraries that haven't been updated yet.)<br> <br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Would type hints be added to the signatures in .rst docs?<span class="HOEnZb"><font color="#888888"></font></span></blockquote><div><br></div><div>I think you and Georg may have to decide what to do. <br></div></div><br>-- <br><div class="gmail_signature">--Guido van Rossum (<a href="http://python.org/~guido">python.org/~guido</a>)</div>
</div></div>