Enable keyword-based exclusion of a single line from docsig checks

[xqt]

Enable keyword-based exclusion of a single line from docsig checks

Currently, docsig does not provide a reliable way to suppress a single diagnostic message on the exact line.

In particular, when a diagnostic is emitted on a decorator line, inline suppression comments such as # docsig: disable or # docsig: disable=SIG402 are not honored.

Proposed feature

Introduce a lightweight, explicit mechanism to exclude a single line from docsig validation.
For example:

@deprecated_signature(since='11.4.0')  # docsig: SIG402
def my_function():
    """This is my docstring.

   Ignore a single test.
   """   # docsig: SIG402

[jshwi]

Hey @xqt

Thanks for opening this

It looks like two separate things are conflated here: a feature request for new syntax, and a bug report about existing syntax on decorated functions

What docsig supports today

Per the directives docs, comment directives must use enable or disable:

• # docsig: disable - disable all checks for that function if inline, or module up until # docsig: enable is used (if at all)
• # docsig: disable=SIG402 - disable specific rule(s) for that function if inline, or module up until # docsig: enable=SIG402 is used (if at all)
• # docsig: disable-next=SIG402- disable specific rule(s) on the next line (useful when the def line is long or when the decorator is on that line)

Directives apply per function, not per physical line. A comment on the def line (or a module-level comment above it) controls which checks run for that entire function. Diagnostics are reported against the function’s line number, but suppression is function-scoped

Decorator-line # docsig: disable=… not being honoured

# docsig: disable and # docsig: disable=SIG402 on the decorator line don’t work at the moment. That does look like a bug: for decorated functions, astroid attributes the function to the decorator line, while inline comments are deferred to the next physical line, so the directive never lines up with the function. That’s separate from adding # docsig: SIG402 shorthand

Workaround for now - put disable-next on the line above the decorator:

# docsig: disable-next=SIG501
@deprecated_signature(since='11.4.0')
def my_function():
    """This is my docstring."""

About the proposed # docsig: SIG402 syntax

# docsig: SIG402 is ambiguous, it doesn’t say whether to enable or disable the rule. It's not really clear what it's doing, unlike noqa. Just to clarify, are you asking for this to be implemented as shorthand for # docsig: disable=...?

Issues with the example as written

• Missing enable/disable - # docsig: SIG402 isn’t valid; use # docsig: disable=SIG402 (see directives)
• SIG402 may not be the right code - SIG402 is params-out-of-order. A decorated function with a minimal docstring like in your example is more likely to hit something like SIG501 (confirm-return-needed), depending on the signature. Worth matching the directive to the actual docsig output
• Comment after the closing """ - directives are per function, not per line. A comment there wouldn’t mean “suppress only this line”; it would still apply to the whole function (if it were parsed at all). The docs show inline directives on the def line, or disable-next on the line above

To move forward

1. Is the goal shorthand # docsig: SIG402, or is fixing # docsig: disable=... on decorator/def lines enough?
2. A minimal file and exact docsig output (message code + line number) so we can confirm the right rule to suppress
3. What you expect the docstring-end comment to do - disable for the whole function matches the current model; line-specific suppression would be new behaviour. Module-level disable / enable around the function also works today:

# docsig: disable=SIG501
@deprecated_signature(since='11.4.0')
def my_function():
    """This is my docstring."""
# docsig: enable=SIG501

Happy to treat decorator-line disable= as a bug either way

Cheers,
Stephen

[jshwi]

Hey @xqt

Fixed the decorator-line disable bug in 1e4e6c0 (fix: honor disable on decorated function lines (#855)). This is being released in v0.90.1.

These now work as expected:

@deprecated_signature(since='11.4.0')  # docsig: disable=SIG501
def my_function():
    """This is my docstring."""

@deprecated_signature(since='11.4.0')
def my_function():  # docsig: disable=SIG501
    """This is my docstring."""

Directives are still function-scoped (enable / disable / disable-next), not per physical line, and # docsig: SIG402 shorthand was not added. Use # docsig: disable=SIG402 (or disable-next) as in the directives docs.

Closing this on that fix.

Cheers,
Stephen