bug#29003: 25.3; Docstring from PEP 257 is filled incorrectly by Emacs

bug#29003: 25.3; Docstring from PEP 257 is filled incorrectly by Emacs

[Radon Rosborough]

I recently noticed that Emacs fills an example docstring given [1] in
PEP 257 incorrectly. With `python-fill-docstring-style' at its default
value of `pep-257', the following code sample:

    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 filled to:

    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
        ...

There are two issues here: the extra newline added, and the unwrapping
of the keyword arguments. The extra newline can be suppressed by
changing the value of `python-fill-docstring-style', but the keyword
argument unwrapping does not appear to be suppressible. This seems
erroneous to me since the value of `python-fill-docstring' would suggest
PEP 257 compliance, i.e. the examples given in PEP 257 should not be a
affected by wrapping. (I also checked out the third-party package
`python-docstring' [2], and it has the same behavior.)

bug#29003: 25.3; Docstring from PEP 257 is filled incorrectly by Emacs

[Charles A. Roelli]

>        Keyword arguments:
>        real -- the real part (default 0.0)
>        imag -- the imaginary part (default 0.0)

I think all Emacs fill commands will fill this as one continous line,
unless you make the newlines between these lines "hard", as with M-x
use-hard-newlines (which is actually a minor mode, I think).

bug#29003: 25.3; Docstring from PEP 257 is filled incorrectly by Emacs

[Radon Rosborough]

> I think all Emacs fill commands will fill this as one continous
> line,

As it currently stands, yes. That doesn't have to be the case,
however. For example, package `python-docstring' can understand reST
syntax, so that:

    def example_function():
        """Initialize engine.

        :param holes: Number of holes.
        :param rounds: Number of rounds.
        :param colors: Number of colors.

        :returns: Game engine instance.
        """
        pass

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.

bug#29003: 25.3; Docstring from PEP 257 is filled incorrectly by Emacs

[Charles A. Roelli]

It would be great if the example given was standard practice, but that
doesn't seem so.  The example also doesn't show how you might document
standard key arguments (without a default), which would be vital in
everyday usage.

bug#29003: 25.3; Docstring from PEP 257 is filled incorrectly by Emacs

[Stefan Kangas]

Radon Rosborough <radon.neon@gmail.com> writes:

>> I think all Emacs fill commands will fill this as one continous
>> line,
>
> As it currently stands, yes. That doesn't have to be the case,
> however. For example, package `python-docstring' can understand reST
> syntax, so that:
>
>     def example_function():
>         """Initialize engine.
>
>         :param holes: Number of holes.
>         :param rounds: Number of rounds.
>         :param colors: Number of colors.
>
>         :returns: Game engine instance.
>         """
>         pass
>
> 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.

Best regards,
Stefan Kangas

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

[Lars Ingebrigtsen]

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