Update docstrings to be consistent with function signature

[cphyc]

PR Summary

With time, many docstrings have grown out of sync with their actual function. This PR attemps to fix as many as possible.

This PR fixes as many as possible:

• Non-compliant docstrings (e.g. * ds : Dataset should be ds : Dataset)
• Arguments mentioned in the docstring that do not exist in the function signature
• Plot callbacks and fixed resolution buffer filters had their signatures incorrectly guessed (see screenshots). Note that the best solution would be to refactor the callbacks and remove the current two hacks to get the proper function signature. See issue ENH: Refactor annotation callbacks #3311 .

The mismatches have been found using https://gist.github.com/cphyc/afc1a143943220ec3a1c5ca16e14cd13 which allows to compare the list of argument parsed from the docstring to the actual signature of the function.

Currently on main

import yt
ds = yt.load_sample("output_00080")
p = yt.SlicePlot(ds, "x", "density")
p.annotate_sphere?

On main (center is missing from the signature):

With this PR:

Note on the signature issue

The origin of the signature mismatch is due to the weird structure we are using to register plot annotation callbacks. Each callback is a class which constructor we were binding to the caller PlotWindow instance using types.MethodType. This function alters the displayed signature by dropping the first argument which is assumed to be self. In our case, because we are binding a constructor method rather than a function, the first argument in the signature is actually the first argument after self in the __init__ method.

Here's a simple example:

>>> import types
>>> class Foo:
...     def __init__(self, arg1, arg2):
...         pass
...         
... class Bar:
...     def __init__(self):
...          self.foo = types.MethodType(Foo, self)
... 
... b = Bar()
... b.foo?
Signature: b.foo(arg2)   # ! Should have been b.foo(arg1, arg2)
Docstring: <no docstring>
Type:      method

[neutrinoceros]

If you're worried about order consistency, please sort the docstring, not the signature itself. Specifically positional arguments (keyword-only arguments can be safely reordered without breaking backwards compatibility however)

[neutrinoceros]

thank's for doing this, here are a couple suggestions

[neutrinoceros]

I agree with the annotated type, but the default value's type should also reflect it, can you fix it too ?

[cphyc]

Should be good now!

[cphyc]

Should be good now!

[cphyc]

I have updated the PR description to explain why this is required.

[neutrinoceros]

I'm happy to have this go in as is given the fact we have a freshly opened issue to remind us that this code is due for a deeper refactor. Thanks again !