Unable to leave noqa outside of docstring

[adithyabsk]

When the noqa is placed outside of the docstring, it is not respected as it works in pydocstyle http://www.pydocstyle.org/en/2.1.1/usage.html. Would greatly appreciate if this could be implemented as otherwise the noqa shows up in the html of the doc.

[terrencepreilly]

That may be possible. Currently, darglint reads the file and then uses the ast module to parse the python source. ast doesn't provide comments. Obviously, we could do a search of the file contents to identify the noqas, but then the line numbers would have to be matched with the docstring line numbers. The logic for that could be kind of convoluted.

I'll give it some thought, and if it can be done somewhat reliably I'll attempt it. If it's too slow, I may hide it behind a flag, though. I'm open for suggestions for implementation if you have any.

[adithyabsk]

Thanks for looking into the idea! This is a real showstopper for adopting this plugin due auto-documentation. Otherwise the noqa's show up in readthedocs when using sphinx.

Not sure how pydocstyle does it but a thought could be to use ast's to get the containing header (module, class, function) and search the file for the noqa on the line(s) defining it.

[rpkilby]

but then the line numbers would have to be matched with the docstring line numbers. The logic for that could be kind of convoluted.

Just quickly glanced at pydocstyle, and it looks like # noqa use is limited to the function signature. I don't you would need to check the docstring lines.

[terrencepreilly]

Thanks, @rpkilby. I took a look as well. It seems that pydocstyle uses the tokenize module, rather than ast. In fact, that may be the more efficient approach, since it would skip the parsing step. You're right that once the docstring is found, finding the appropriate # noqa should be simple.

[adithyabsk]

While I would still love for this feature to be implemented to be consistent with pycodestyle I found a workaround to implement this package for my use case. Simply using sphinx's comment to prevent the text from showing up in the docstring works.

@property
def attr(self):
"""Some attr

:gettr: Returns attr

:setter: verfies attr before setting

:type: attr type

.. # noqa: I201
"""
    return self._attr

[art049]

Another workaround I just found to hide the noqa from the IDEs as well is to use a markdown comment (actually an HTML one)

@property
def attr(self):
"""Some attr

:gettr: Returns attr

:setter: verfies attr before setting

:type: attr type
<!---
# noqa: I201
-->
"""
    return self._attr

[s-weigand]

When using numpy style docstrings @art049 's workaround doesn't work. For @adithyabsk's workaround to work properly, you need to have at least two blank lines above the noqa.

IMHO this should be the example in the docs.

[stephen-dexda]

Unfortunately neither workaround hides the directives from help(foo).

To follow up on @terrencepreilly's reply to #148 which I opened about the same issue (didn't realise there was an open bug already):

Whenever possible, docstrings shouldn't need to use noqa statements.

There are a number of cases where Darglint generates false positives under certain circumstances, so #noqa is needed to handle these, especially if for example linting is part of a CI process (necessitating a "pass" from the linter).

Where that's not practical because of a project's existing style, then it should be ignored in the configuration.

This means errors in that category that aren't false positives would be missed.

I don't think it decreases the docstring clarity.

I'd respectfully disagree - IMO linter directives should never show up in help() or in generated documentation.