bug#29003: [python.el] Docstring from PEP 257 is filled incorrectly by Emacs

[Lars Ingebrigtsen <larsi@gnus.org>]

Stefan Kangas <stefan@marxist.se> writes:

    > > > def complex(real=0.0, imag=0.0):
    > > >     """Form a complex number.
    > > > 
    > > >     Keyword arguments:
    > > >     real -- the real part (default 0.0)
    > > >     imag -- the imaginary part (default 0.0)
    > > >     """
    > > >     if imag == 0.0 and real == 0.0:
    > > >         return complex_zero
    > > >     ...

[...]

>> is not modified when filled. The question is whether the example given
>> by PEP 257 should be considered "standard" syntax for introducing
>> keyword arguments, and whether such syntax should be supported by
>> Emacs in a similar way to how `python-docstring' supports reST syntax.
>
> I think this should ideally be supported by Emacs, but it should be
> configurable and disabled by default.

I think introducing these kinds of semantics in doc strings is
inherently brittle (unless really well-defined).  For instance,

      If this is a doc string, and then I
      pause -- using a double dash for a
      pause is common -- then we'd be filling
      things differently.

So I don't think changing the pep-257 style would be appropriate, and I
think adding a user option for this wouldn't receive much use.  So I'm
closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no