Support paragraph breaks in python block comments. #5148
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The current python filetype module treats a single empty comment line (typically created by hitting enter twice while in a block comment) as the end of the block comment, deleting the empty comment line and ending comment prefix copying. This runs contrary to PEP8, which explicitly allows for paragraphs in block comments, with an empty comment as the paragraph separator (see https://peps.python.org/pep-0008/#block-comments for the actual text).
This change implements support for using a single empty comment as a paragraph separator, with two consecutive empty comments being treated as the end of the block comment; both empty comment lines are deleted and comment prefix copying is ended.
This would close issue #5147
This change basically means that you can hit enter twice while you're in a block comment, and you'll get an empty comment and the cursor at the start of a new commented line - if you enter text the block comment will continue as normal, if you hit enter again at this point the block comment is terminated, the empty comments are deleted, and you go back to regular code. This follows the basic logic of the current implementation, while allowing for paragraph breaks in block comments.
This behaviour arguably isn't ideal, particularly with the two empty comments disappearing suddenly - that rather goes against the principle of least surprise. But given the way block comments work it's hard to see a better approach - something like Ctrl-enter, perhaps? I don't know how that would work with a modal editor like Kakoune, though.
Possible issues with the whole idea aside, I'm not confident this is the best possible implementation - it was a lot fiddlier than I anticipated to make it work the way I intended, and it doesn't feel very elegant. There may be cases that aren't handled properly, though I've tried to make it reasonably robust. Any suggestions for improving the code would be appreciated.
I've added tests in the
regression/5147-python-block-comment-paragraphs
directory, if there's a more appropriate place for them please let me know and I'll relocate them. Additional test cases or a better way to implement them are welcome.I've already submitted a copyright waiver for previous contributions, I assume that's still considered valid.