Several new bugs with paragraph filling

Bug #1066489 reported by Barry Warsaw
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
python-mode.el
Fix Released
High
Andreas Roehler

Bug Description

Running with the latest bzr, I'm seeing several new bugs with paragraph filling of docstrings.

Take for example, this method definition in Mailman:

class IBanManager(Interface):
    """The global manager of email address bans."""

    def ban(email):
        """Ban an email address from subscribing to a mailing list.

        The `IBanManager` is created by adapting an `IMailingList` or ``None``.
        For global bans, use ``None``.

        When an email address is banned, it will not be allowed to subscribe
        to a the named mailing list. This does not affect any email address
        already subscribed to the mailing list.

        It is also possible to add a 'ban pattern' whereby all email addresses
        matching a Python regular expression can be banned. This is
        accomplished by using a `^` as the first character in `email`.

        When an email address is already banned for the given mailing list (or
        globally), then this method does nothing. However, it is possible to
        extend a ban for a specific mailing list into a global ban; both bans
        would be in place and they can be removed individually.

        :param email: The text email address being banned or, if the string
            starts with a caret (^), the email address pattern to ban.
        :type email: str
        :param mailing_list: The fqdn name of the mailing list to which the
            ban applies. If None, then the ban is global.
        :type mailing_list: string
        """

Now, I see the new py-fill-docstring-style, however the default is not backward compatible. For backward compatibility, pep-257-nn should be the default.

More importantly, fill-paragraph (M-q) no longer fills just the paragraph point is in, it fills the entire docstring. This is quite bad because it means it will rewrap the :param: sections at the bottom of the docstring, and possibly other paragraphs in the docstring that should not be rewrapped. So the first bug is that fill-paragraph is too aggressive by ignoring empty lines to delimit the paragraphs. It should fill only the paragraph point is in.

The second big bug here is that after filling, you are left with non-empty blank lines in between the paragraphs. Lines in the above example where are blank, and actually empty, are left after filling with 8 spaces. Still blank, but with 8 spaces added.

Changed in python-mode:
assignee: nobody → Andreas Roehler (a-roehler)
milestone: none → 6.1.0
importance: Undecided → High
Changed in python-mode:
status: New → Fix Committed
Changed in python-mode:
status: Fix Committed → Fix Released
To post a comment you must log in.
This report contains Public information  
Everyone can see this information.

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.