darglint
darglint copied to clipboard
No missing blank line at the end of the docstring is reported
Thanks for the awesome tool. I have started using it on a Python project and am very happy with it. There are however a couple of things I'd like to report to see how difficult they are to fix.
Talking only Google docstring style.
If I understand it right, there should be a blank line before the closing triple quotes, however it is not reported.
def do_sum1(var1, var2):
"""Sums two numbers.
Description is here Description is here Description is here Description is here.
Description is here Description is here Description is here Description is here.
Description is here Description is here Description is here Description is here.
Args:
var1: Variable 1
var2 (float): Variable 2
Returns:
int: sum of two ints
Raises:
ValueError: If passing non integer values
"""
if not all(
[ isinstance(var, int) for var in [var1, var2]]
):
raise ValueError("Only integers are supported")
return var1 + var2
I except the docstring to be
......
Raises:
ValueError: If passing non integer values
"""
Just taking a quick look at the docstring section, I don't see any examples with a blank line. e.g.,
class SampleClass(object):
"""Summary of class here.
Longer class information....
Longer class information....
Attributes:
likes_spam: A boolean indicating if we like SPAM or not.
eggs: An integer count of the eggs we have laid.
"""
Thanks for looking at the issue. You are right that at the very section you've looked at, there is no blank line. However, here on Napoleon page all docstrings have the blank line https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html - hence my concern
@AlexArcPy, I agree with you that it would be nice to enforce a blank line at the end of a docstring. (That's my preference, too.) Like rpkilby said, though, Google's style guide doesn't enforce that in their examples.
This is, in fact, one of the things I would like to support through stylistic warnings. (That is, the format is not incorrect, but not what is preferred.) I've been away from working on darglint for the last two months while I moved across the country and started a new job. I'll probably look into it again this weekend, though it's a bigger (and much more difficult) change to make.
I'll mark this as an enhancement, and put it under the GLR/ambiguous grammar milestone. In the meantime, if you wanted you could always fork and add it in around here. You would just check if function.docstring.endswith('\n')
. If not, you could append an error to self.errors
. It's a little hacky, but it would work until I (or anyone else) has resolved the stylistic errors milestone. If you decide to go that route, let me know if you need any help.