Rewrap
Rewrap copied to clipboard
stkb
another python docstring problem
Hi, see various python docstring formatting issues but not this one. A line like the below:
"""This is a long doc-string in python. If this line extends beyond the column limit and is followed by another line of this comment, an the ending triple
quotes will be placed in the wrong position, cutting in half this comment."""
gets rewrapped into:
"""This is a long doc-string in python. If this line extends beyond the column
"""limit and is followed by another line of this comment, an the ending triple
quotes will be placed in the wrong position, cutting in half this comment."""
Notice that additional triple quotes on the second line. The result isn't even a valid string.
Note that the problem does not occur if the first line is just the triple quotes.
This was caused (in part) by the change in v1.16 where Python docstrings are now parsed as rST. The problem is rST is indent sensitive and so it sees the 1st & 2nd lines in your example as separate paragraphs.
It's gonna take me a little while to fix. Workarounds until then are:
- Downgrade back to v1.15.x where docstrings are parsed as markdown instead (this will also be added as an option in the future)
- (As you note) put the opening triple quotes on a separate line instead.
- Format the comment like this:
""" Text text
more text but at the same indent
Following paragraphs can be indented at this level
Or at this level if you prefer."""
Chiming in for this issue. I know it's been mentioned it would take some time, but I'd like to add some extra context.
def get_message_id(self) -> int:
"""Increments the message ID, returns old value. Use in conjunction of sending messages, to always get a unique message ID
Returns:
int: The old message ID
"""
Will, as the OP describes, rewrap into
def get_message_id(self) -> int:
"""Increments the message ID, returns old value. Use in conjunction of
"""sending messages, to always get a unique message ID
Returns:
int: The old message ID
"""
def get_message_id(self) -> int:
"""Increments the message ID, returns old value. Use in conjunction of
"""sending messages, to always get a unique message ID
Returns:
int: The old message ID
"""
The suggested workaround of changing the indentation of the Docstring to def get_message_id(self) -> int: """ Increments the message ID, returns old value. Use in conjunction of sending messages, to always get a unique message ID
Returns:
int: The old message ID"""
still incorrectly rewraps the docstring, keeps the indentation, but also squishes following lines (as expected based on the documentation)
```python
def get_message_id(self) -> int:
""" Increments the message ID, returns old value. Use in conjunction of
""" sending messages, to always get a unique message ID
Returns: int: The old message ID"""
As a sidenote: When using a formatter such as Black, the docstring will be auto-reformated to the one towards the top of this message, to match the PEP recommendations.
love the extension! just wanted to bump this issue -- currently i have to manually reformat the first line of every python docstring, and it would be super cool if the extension could handle this part automatically too :grinning:
