Docstrings extractors update, fix PR01 and PR02 #3016

[chrishalcrow]

Update docstrings in public Extractors module functions to be compliant with PR01 and PR02 from numpydoc.
(also fix a whitespace error in Preprocessing)

Two controversial changes:

• This update BREAKS BiocamRecordingExtractor, SpikeGadgetsRecordingExtractor and BlackrockRecordingExtractor, which all had an unused block_index parameter in their __init__. I think it's better to delete these than to document something which is unused => can create unexpected behaviour. Is this a problem @alejoe91 @samuelgarcia ?
• read_openephys still fails PR01 and PR02 because the Parameters are bundled in a kwargs dict. But the Parameters are very helpful and, from the user point of view, can be passed as "normal" parameters. Not sure what to do. Code here:

  spikeinterface/src/spikeinterface/extractors/neoextractors/openephys.py

  Line 304 in d963aa2

  def read_openephys(folder_path, **kwargs):

The rules are...

https://numpydoc.readthedocs.io/en/latest/validation.html#
"PR01": "Parameters {missing_params} not documented",
"PR02": "Unknown parameters {unknown_params}",

...and they ensure that the function argument agrees with the Parameters listed in docstrings.

[alejoe91]

Thanks Chris! Ok to remove unused block_index in my side. @samuelgarcia ok?

[JoeZiminski]

(Not knowing anything about the actual code functionality) it would be very cool to remove **kwargs from read_openephys() and replace with the full accepted params list. My preference is to avoid **kwargs wherever possible for public functions, even if there is duplication, as more robust. With **kwargs it is possible for the user to pass a mis-spelled argument with no ill affect, it will not crash just silently not perform the desired action.

[alejoe91]

(Not knowing anything about the actual code functionality) it would be very cool to remove **kwargs from read_openephys() and replace with the full accepted params list. My preference is to avoid **kwargs wherever possible for public functions, even if there is duplication, as more robust. With **kwargs it is possible for the user to pass a mis-spelled argument with no ill affect, it will not crash just silently not perform the desired action.

The "problem" is that the function dispatches wither the legacy or the binary format. We could extend the signature, but then we'll need to route the params accordingly!

[JoeZiminski]

Nice! I think it is okay to remove these unused kwargs, they should either be removed or raise an error now and removed later. One option is to raise an error to explain, and deprecating in the version-after-next? More overhead thought to remember to remove, would have to add as an issue + milestone. If I understand correctly these are not critical arguments (e.g. it will be obvious what data blocks are returned, not like it can cause silent or unknown changes to results). In which case just remove I think!