Improve API documentation of sndrecv and SuperSocket functions.

[polybassa]

No description provided.

[codecov]

Codecov Report

Merging #4114 (81a7975) into master (6829f4c) will increase coverage by 32.30%.
The diff coverage is 100.00%.

Additional details and impacted files

@@             Coverage Diff             @@
##           master    #4114       +/-   ##
===========================================
+ Coverage   49.67%   81.98%   +32.30%     
===========================================
  Files         342      349        +7     
  Lines       76267    81853     +5586     
===========================================
+ Hits        37886    67105    +29219     
+ Misses      38381    14748    -23633     

Files	Coverage Δ
scapy/sendrecv.py	87.68% <100.00%> (+48.12%)	⬆️
scapy/supersocket.py	75.64% <ø> (ø)

... and 263 files with indirect coverage changes

[gpotter2]

Thanks, that's a cool PR.

[polybassa]

Thanks.. can we merge it?

[gpotter2]

I'll just try to test it and merge it when it's done, but it looks alright.

I would also like to fix readthedocs builds, which have been broken for a while.

[polybassa]

whats broken? Can I assist?

[gpotter2]

Builds fail (i.e. doc is not updated).

https://readthedocs.org/projects/scapy/builds/

This happens in weird cases where dependencies don't match between readthedocs and our github tests.

Just bumped the dependencies, it should get back to working.

[polybassa]

ok, great.. so we can merge this one?

[polybassa]

Ready for merge

[gpotter2]

Okay there are many issues with this PR.
Generally help(srp) is unreadable, and the variables don't have the same name, nor are in the same order in the function and in the docstring.

For readers, this is what help(srp) looks like:

Help on function srp in module scapy.sendrecv:

srp(x, promisc=None, iface=None, iface_hint=None, filter=None, nofilter=0, type=3, *args, **kargs)
    Send and receive packets at layer 2

    :param pks: SuperSocket instance to send/receive packets
    :type pkt: SuperSocket

    :param pkt: Packet or iterable of packets to be sent.
    :type pkt: _PacketIterable
    :param timeout: How much time to wait after the last packet
                    has been sent. Defaults to None.
    :type timeout: Optional[int]
    :param inter: Delay between two packets during sending. Defaults to 0.
    :type inter: Optional[int]

    :param verbose: Set verbosity level. Defaults to None.
    :type verbose: Optional[int]

    :param chainCC: If True, KeyboardInterrupts will be forwarded.
                    Defaults to False.
    :type chainCC: Optional[bool]

    :param retry: If positive, how many times to resend unanswered packets.
                  If negative, how many times to retry when no more packets
                  are answered. Defaults to 0.
    :type retry: Optional[int]

• arguments are not in order
• don't have the correct names
• and the typing information makes it unreadable

[polybassa]

I totally agree, srp and srp1 is broken. Sorry. I'll fix it

[polybassa]

@gpotter2 Cleaned it up.

[polybassa]

Could you please review?

[polybassa]

@gpotter2 I've resolved the conflicts on this PR, could you please have a look?