NatSpec association breaks when a `// solhint-disable` directive appears between the NatSpec block and a function

[pvandervos-circle]

Solhint appears to require NatSpec comments to be directly adjacent to a function declaration in order to count as documentation for use-natspec. However, placing a // solhint-disable ... directive between the NatSpec block and the function causes Solhint to stop associating that NatSpec with the function, producing a use-natspec warning.

Minimal reproduction

pragma solidity ^0.8.30;

contract Test {
    /**
     * @notice Example function
     */
    // solhint-disable-next-line any-rule
    function f() external {}
}

Actual behavior

Solhint emits a use-natspec warning (e.g., missing @notice / missing documentation), as if the NatSpec block were not present.

Expected behavior

Solhint should still treat the NatSpec block as attached to the following function even if there is a Solhint directive comment between them. Conceptually, // solhint-disable-next-line ... should be “transparent” for NatSpec association.

Why this matters

A common pattern is to place lint directives immediately before the statement they apply to. If doing so breaks NatSpec association, developers are forced into worse alternatives:

• Use solhint-disable-line at end-of-line (often rejected by formatters / line-length rules)
• Use block disables (solhint-disable / solhint-enable) that are verbose and broader than intended

Workarounds (current)

1. End-of-line directive (often not allowed by formatters/line-length limits):

function f() external {} // solhint-disable-line any-rule

2. Block disable/enable around the function (verbose / broader than needed):

// solhint-disable any-rule
/**
 * @notice Example function
 */
function f() external {}
// solhint-enable any-rule

Suggested fix (high level)

When collecting NatSpec for a function node, Solhint should skip over Solhint directive comments (e.g., solhint-disable-next-line, solhint-disable-line, etc.) when determining the “immediately preceding” documentation block