Skip to content

Keep a multi-sentence summary intact when it is followed by a description - #397

Closed
kritagyadubey wants to merge 1 commit into
PyCQA:masterfrom
kritagyadubey:fix-315-summary-split-order
Closed

kritagyadubey wants to merge 1 commit into
PyCQA:masterfrom
kritagyadubey:fix-315-summary-split-order

Conversation

@kritagyadubey

Copy link
Copy Markdown

When a summary has more than one sentence and is followed by a description,
do_split_summary splits at the first period but then places the rest of the
summary in the wrong position. On master this mangles the docstring: a blank line
ends up between the first and second sentence, and the description is appended to
the end of the summary with extra spaces.

Given:

def foo():
    """First sentence is here. Second sentence is long and split in two. I even have a third sentence here.

    And other text here.
    """

master produces:

def foo():
    """First sentence is here.

    Second sentence is long and split in two. I even have a third sentence
    here.     And other text here.
    """

The rest of a multi-sentence summary still belongs to the summary, so this inserts
it directly after the first sentence and leaves the blank line where it separates
the summary from the description:

def foo():
    """First sentence is here. Second sentence is long and split in two. I even
    have a third sentence here.

    And other text here.
    """

This adds unit tests for do_split_summary (single-line and two-line summaries)
and an end-to-end case in do_format_code.toml. Both fail on master and pass
with the change.

The original report in #315 showed the summary lines reordered. That exact
reordering no longer occurs after later refactors, but the summary/description
boundary is still mangled on master, so the issue remains open.

Fixes #315

do_split_summary() merged the remainder of a multi-sentence summary into the line that followed it, overwriting the blank line that separates the summary from the description.  With no blank line left, the wrapped summary and the description then ran together on a single line.

Insert the remainder directly after the first sentence instead, which keeps the blank separator in place.

Fixes #315
@kritagyadubey kritagyadubey closed this by deleting the head repository Oct 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Multiline summary is not split correctly

1 participant