noqa comments in docstring pollute code's documentation

[stephen-dexda]

The current implementation of noqa, as comments in the docstrings, results in the pollution of the code's documentation (e.g. when using doc. generators, help(function) etc.) with linter directives, which is counter to the aim in broad terms of Darglint (i.e. to improve code documentation quality).

Would it be possible to implement this instead (or alternatively) as standard comments outside of the docstring itself (maybe just below), using the "separate line" formats from https://github.com/terrencepreilly/darglint#ignoring-errors-in-a-docstring? So for each of the examples there, the following instead:

def we_dont_want_a_returns_section():
  """Return the value, 3."""
  # noqa: DAR201
  return 3

def a_bound_function(self, arg1):
  """Do something interesting.

  Args:
    arg1: The first argument.

  """
  # noqa: DAR101 arg1
  arg1.execute(self)

def always_raises_exception(x):
    """Raise a zero division error or type error.o

    Args:
      x: The argument which could be a number or could not be.

    Raises:
      ZeroDivisionError: If x is a number.
      TypeError: If x is not a number.

    """
    # noqa: DAR402 ZeroDivisionError
    # noqa: DAR402 TypeError
    x / 0

I guess an obstacle to this might be that ast doesn't retain comments, but there seem to be a number of alternatives that might work instead, at least for this specific purpose?

[terrencepreilly]

There Issue #21 already for this. It may be possible, but it's pretty low priority for me.

which is counter to the aim in broad terms of Darglint (i.e. to improve code documentation quality).

I don't entirely agree with this. Whenever possible, docstrings shouldn't need to use noqa statements. Where that's not practical because of a project's existing style, then it should be ignored in the configuration. Some noqa statements are unavoidable, but they should be uncommon, and in that case, I don't think it decreases the docstring clarity.