Home Original page

[Python-Dev] The docstring hack for signature information has to go

Georg Brandl g.brandl at gmx.net
Tue Feb 4 18:30:18 CET 2014 
Am 04.02.2014 13:14, schrieb Antoine Pitrou:
> On Tue, 04 Feb 2014 02:21:51 -0800
> Larry Hastings <larry at hastings.org> wrote:
>> On 02/04/2014 01:41 AM, Georg Brandl wrote:
>> > Clever, but due to the "hidden" space it also increases the frustration factor
>> > for people trying to find out "why is this accepted as a signature and not this".
>> >
>> > I don't think a well-chosen visible separator is worse off, such as "--\n".
>> 
>> I could live with that.  To be explicit: the signature would then be of 
>> the form
>> 
>>     <name-of-function(...)\n--\n
>> 
>> The scanning function would look for "<name-of-function>(" at the 
>> front.  If it found it it'd scan forwards in the docstring for 
>> ")\n--\n".  If it found *that*, then it would declare success.
> 
> This would have to be checked for layout regressions. If the docstring
> is formatted using a ReST-to-HTML converter, what will be the effect?

The "--" will be added after the signature in the same paragraph.

However, I don't think this is a valid concern: if you process signatures
as ReST you will already have to deal with lots of markup errors (e.g. due
to unpaired "*" and "**").

Tools that extract the docstrings and treat them specially (such as Sphinx)
will adapt anyway.

Georg
More information about the Python-Dev mailing list