[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