rstdrift: Sphinx :param: and epytext @param against the signature

[darkdi]

Same defect docdrift looks for, in the two dialects it says it does not parse. Field form: :param str name: in Sphinx and @param socketfd: in epytext.

I ran into this the boring way. gdrift came back with zero on Pillow, tqdm and dbt-core, and the coverage line said why: not one Args: block in any of those trees. Not clean, wrong dialect. Pillow turns out to have 220 callables written with :param: and nothing in the kit was reading them.

The @ sigil surprised me more. On Twisted the : form finds 8 callables in the whole tree; adding @ to the same pattern finds 2662. A tool reading only : would have called Twisted clean and moved on, which is the failure mode the coverage line exists to catch.

Two design choices worth arguing about. *args makes a finding soft instead of skipping the function: Pillow's Image.eval(image, *args) documents :param function: and that entry is the only thing telling a reader what to pass second, so deleting it makes the docs worse and a human should decide. **kwargs is still skipped outright since anything may legitimately be documented there. Second, self and cls stay in the signature set. Dropping them turned a module-level decorator whose real argument is called cls into a finding, and turned every honest :param self: in langchain-descended code into one too.

Blind spots are in the docstring, and two of them are recorded rather than fixed. A class documenting its attributes under :param: reads as a finding and is not one, and there is no way to tell an attribute from an argument by the field alone. A duplicated field name is invisible, since both names exist in the signature: certbot has :param bool default: twice and the second one means ipv6.

Twelve tests, each from a place the check actually ran. Conformance passes, common.PLACE and the sweep plan know about it, README has a row. Five entries in FALSE-POSITIVES, numbers 96 to 100, including two that cost me something: text-based editing in this dialect (:param rdata: occurs 9 times in salt, 6 of them correct) and a deletion that left an empty section header and turned qutebrowser CI red.

Findings so far: moto 5, certbot 16, salt 26, twisted 8. Scrapy, click and mitmproxy came back clean with the coverage line showing 47, 94 and a real count, so that is clean rather than unread.